Skip to content

fix(compiler): land border-x/border-y colours on border keys React Native draws - #581

Merged
danstepanov merged 5 commits into
nativewind:mainfrom
sammoore:fix/logical-borders
Nov 20, 2026
Merged

danstepanov merged 5 commits into
nativewind:mainfrom
sammoore:fix/logical-borders

Conversation

@sammoore

@sammoore sammoore commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Precedes #393 -- both resolve a core issue that amounts to a regression relative to Nativewind v4 behavior, but this PR omits the bits that do not affect Tailwind users, and does so with more targeted changes. I suggest leaving the other PR open as it can be rebased and updated to resolve the remaining issues (see the "Not in this PR" section below).

Problem

React Native has no borderInlineColor. borderBlockColor is ranked against borderTopColor in opposite orders on each platform: Android's BorderColors.kt reads BLOCK_START ?: TOP ?: BLOCK, while Fabric's shared resolver (iOS) puts block above top.

On main:

  • Tailwind border-x-<colour> with a themed colour (a variable redefined for dark mode or an app theme, so it reaches the runtime) compiles to borderInlineColor. Neither edge gets the colour.
  • Every border-y-<colour> compiles to borderBlockColor. So border-y-red-500 border-t-blue-500 paints a blue top edge on Android but a red one on iOS.
  • border-block writes its colour to borderBlockColor too.

Nativewind v4 (Tailwind CSS 3) emitted border-left/right-color and border-top/bottom-color, so all of these worked there. This is a v4 regression. No v5 release had it working: #108 moved these properties to logical keys.

Solution

Each axis colour compiles to one declaration per edge, at every arity, literal or var():

CSS React Native keys
border-inline-color borderStartColor / borderEndColor
border-block-color borderTopColor / borderBottomColor
border-block (colour) borderTopColor / borderBottomColor
  • Cascade order: the split happens at compile time, so a later edge colour (border-s-*, border-t-*, border-b-*) replaces its edge in cascade order. Nothing changes at runtime, and it doesn't depend on fix(native): resolve declarations in cascade order once an element's variables are set #474.
  • Dark mode: a light-dark() value in these properties sends its dark half to the same edge keys. To allow that, StylesheetBuilder.descriptorProperty becomes descriptorProperties[].

The block axis reverses #108's choice of borderBlockColor. That's deliberate: the edge keys follow the cascade on both platforms, and they match what v4 rendered.

Source: +67/−19 in src/compiler/declarations.ts and src/compiler/stylesheet.ts.

Tailwind impact

Scanned 32 utilities in two modes:

  • Folded: the theme colour is inlined at build time.
  • Kept: the theme colour is redefined, so it stays a variable.

Results:

  • Folded: border-x-* is unchanged (already right). All 9 border-y-* cases move from borderBlockColor to top/bottom.
  • Kept: all 17 changed cases move from borderInlineColor to borderStartColor/borderEndColor. This includes border-x-* border-s-*, border-y-* border-t-* and border-y-* border-b-*, which now resolve in cascade order.
  • No utility throws, before or after.

Performance

  • Microbenchmark (Hermes, calculateProps only): a kept border-x-<colour> now resolves its variable once per edge, about +1.8 µs per element. That's the same cost as writing border-inline-start-color: var(--c); border-inline-end-color: var(--c) by hand on main.
  • Full suite:
    • The new scenario, mount, themed axis border colour, renders 1000 themed cards with border-x-2 border-x-primary. It is within noise against main (+0.3% to +1.0%).
    • Every other scenario is within −1.3% to +3.5%.

Not in this PR

Kept from #393 as follow-ups:

Tests

  • src/__tests__/compiler/logical-borders.test.ts: compiled output for each logical property, literal and var().
  • src/__tests__/native/logical-borders.test.tsx: rendered keys under each cascade order, var() and light-dark().
  • src/__tests__/vendor/tailwind/borders.test.tsx: Tailwind border-x-* / border-y-*.

yarn test: 98 suites, 1829 tests pass.

Based on #393 by @YevheniiKotyrlo. Their commit is kept as is; the follow-up commits move the var() handling from runtime to compile time and set aside the parts that depend on #474.

YevheniiKotyrlo and others added 5 commits November 20, 2026 14:59
border-block-color wrote borderBlockColor when its edges matched and
borderTopColor / borderBottomColor when they did not, so a later
border-top-color sat beside the axis key instead of replacing it, and
Android and iOS rank the two oppositely. Each axis colour now lands on its
edge pair at every arity, and a light-dark() component opens its dark rule
over the edge it feeds.

A var() kept the axis colours and the six logical shorthands off the parsed
path: border-inline-color: var(--c) wrote borderInlineColor, which React
Native lacks, and border-inline: var(--b) reached it as a list. Each now
resolves at runtime onto the same keys the compiler writes, reading as many
values as the variable substitutes, as border-inline-width already does. A
var() edge style drops as quietly as solid, since an unknown value is not a
known non-solid one, and a runtime-parsed value that compiles to nothing
declares nothing.
border-inline-color: var(--c) and border-block-color: var(--c) resolved
through a runtime shorthand, which applies after every other declaration
of the element. A later edge colour on a different key then lost to it:
.a { border-inline-color: var(--c) } .b { border-inline-start-color: blue }
painted the start edge --c. Fixing that ordering is nativewind#474's job.

Each axis colour now compiles to one declaration per edge, the shape
border-inline-start-color: var(--c) already has, so a later edge colour
replaces it in cascade order without nativewind#474. Two literal tokens
(var(--a) var(--b), red var(--b)) still split onto start and end.

Dropped: a single var() that substitutes two colours (--c: red blue) no
longer splits; both edges get the list, which React Native's
normalizeColor leaves unset (no throw). Main sent the same list to
borderInlineColor / borderBlockColor. The runtime handler that covered it
is in patches/393-logical-border-color-runtime.patch, to land after nativewind#474.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
border-inline, border-block and their -start / -end forms with a var()
went through new runtime handlers. Tailwind emits none of them, and the
handlers apply after every other declaration of the element, so until
PR nativewind#474 lands a later edge longhand loses to them:
.a { border-inline: var(--b) } .b { border-inline-start-color: blue }
paints the start edge in --b's colour. Main sends the list to
borderInline* untouched, which React Native ignores without throwing.

The handlers and their tests are in
patches/393-logical-border-shorthand-var.patch, to land after nativewind#474.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The PR merged parseBorderInlineStyle and parseBorderBlockStyle into one
renamed parser, inlined parseBorderBlockWidth, dropped a var() edge style
(border-inline-style: var(--tw-border-style), which Tailwind's
border-x-* / border-y-* emit) without its warning, and stopped a runtime
shorthand that compiles to nothing from declaring anything. None of it is
needed for the edge colours, none of it prevents a throw, and the last
one no longer applies once the axis colours compile to edges.

Restored as main has them. The quiet var() edge style is in
patches/393-quiet-var-edge-style.patch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… has it

The PR also pointed light-dark()'s dark half at the right key for
border-inline, border-inline-start / -end, border-block-start / -end and
the renamed -color longhands (border-inline-start-color: light-dark(...)
put its dark half on borderInlineStartColor). That's a separate, older
bug: main has it for every one of these, Tailwind emits no light-dark(),
and nothing throws.

Kept: per-edge light-dark() in border-block-color, border-inline-color
and border-block, because their light half now lands on the edge keys
and a dark half left on borderBlockColor would rank against it
differently on Android and iOS.

The rest is in patches/393-light-dark-edge-shorthands.patch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@danstepanov
danstepanov merged commit 0ef4ec8 into nativewind:main Nov 20, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants