# Design authority — which external standard owns which decision **Status:** accepted · 2026-09-07 ## Why this document exists Every design question that has no external answer gets answered by us, in a meeting, again. That is the expensive part — not the code. This file names, per layer, the outside system we defer to, so the next question is a lookup instead of an invention. It changes no code by itself. It is the tie-breaker a reviewer points at. ## The layers, and who owns each | Layer | Authority | Status in this repo | | ------------------------------------------------------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Interaction semantics, keyboard, ARIA | **WAI-ARIA APG** | already followed — 33 references in `src/` | | Behaviour primitives | **Radix** | already the implementation — 193 references | | Component composition shape | **shadcn** | already the structural convention — 23 references | | Component taxonomy / grouping | **Ant Design** groups | already the catalog shape: `data-entry`, `data-display`, `layout`, `feedback`, `navigation`, `general` — a naming precedent, nothing is installed | | Colour foundation | **SmartHR**, brand roles aside | the NEUTRAL spine is SmartHR's — `--foreground` = TEXT_BLACK, `--border` = BORDER. `--primary` was SmartHR MAIN `#0071bd` until identity v2.3 took the brand roles back: it is GoDX violet `#7A00FF` today | | **Derived colour — the interaction states hanging off each seed** | **Measured contrast (WCAG 2.2 / JIS X 8341-3)** | Authored in `src/tokens/derived.css`; no algorithm derives them. Four contrast suites read that file and hold every value to a threshold, and a fifth holds it to the seed's HUE (gh#648) — see below | | **Japanese UI convention — density, JP typography, form patterns** | **SmartHR** | **NEW — this decision.** Extends SmartHR from "where the colours came from" to the authority for how a JP business screen behaves | | **Japanese accessibility / public-sector convention** | **デジタル庁 Design System** (Digital Agency) | **NEW — this decision.** The reference when a JP customer asks which standard a screen meets (JIS X 8341-3) | | **Spacing, density, type scale, information architecture** | **IBM Carbon** | **NEW — this decision** | The first five were already true and merely unwritten. The last three are the choices being made here. Carbon fills the one layer that had no outside answer at all: page rhythm, table density, form layout, when to reach for which container. That gap is why `PageContainer` presets, `MasterDetail`, `CenteredShell` and the `AuthShell` variants were each designed from scratch. ## Why Carbon for that layer **It is the closest fit to what this library is for.** Internal SaaS, dense, neutral, legible — that is Carbon's design brief almost verbatim. Its visual language is deliberately plain, so it does not fight the SmartHR colour foundation already in `foundation.css`. **It is the cheapest to adopt, measurably.** The spacing scale here already matches Carbon's on 8 of 9 steps: | `@godxjp/ui` | px | Carbon | | ------------ | ------ | ---------------------------------------- | | `--space-1` | 4 | `spacing-02` | | `--space-2` | 8 | `spacing-03` | | `--space-3` | 12 | `spacing-04` | | `--space-4` | 16 | `spacing-05` | | `--space-5` | **20** | **no equivalent — Carbon steps 16 → 24** | | `--space-6` | 24 | `spacing-06` | | `--space-8` | 32 | `spacing-07` | | `--space-10` | 40 | `spacing-08` | | `--space-12` | 48 | `spacing-09` | Body size agrees too: Carbon's `body-compact-01` is 14px, and `--font-size-base` is 14px. **It is the most actively maintained of the candidates**, which matters when the point is to follow someone rather than lead. Measured 2026-09-07 from the GitHub API: | System | Last commit | Commits, 90 days | | --------------------- | ----------- | ---------------- | | Carbon (IBM) | 2026-09-04 | **418** | | Fluent UI (Microsoft) | 2026-09-06 | 220 | | Polaris (Shopify) | 2026-08-05 | — | | SLDS (Salesforce) | 2026-06-02 | **0** | | Primer (GitHub) | 2025-07-01 | 0 | ## Why not the others **Salesforce Lightning** was the first instinct and is a reasonable one — it is the archetypal enterprise system. Two things rule it out. Its public repo has not moved since June 2026 (SLDS 2 lives in separate `salesforce-ux/design-system-2` repos on a much slower cadence), and the part of SLDS with the most value is bound to Salesforce's own object model — record home, related lists, object pages — which does not transfer to a product that is not Salesforce. **Fluent UI** is complete (54 component packages) and extremely well maintained. It loses on fit, not quality: its guidance is written for Microsoft product surfaces and its visual language carries more Windows/Office flavour than a white-label framework wants. **Apple HIG** is platform guidance for macOS/iOS. It has close to nothing to say about a dense web admin table. **Polaris** has the best content-design guidance of the group, worth borrowing from for microcopy, but its patterns assume the Shopify admin. **Atlassian** is a genuine alternative to Carbon and would also work. Carbon wins on being more visually neutral and on the spacing scale already matching. ## The Japanese market comes first, and it outranks Carbon The customers are Japanese businesses. Where a Western system and a Japanese one disagree, **the Japanese one wins for anything the user reads or touches** — typography, line rhythm, density, form conventions, wording. Carbon keeps geometry (the spacing steps, the 4px grid) because that layer is culture-neutral. **SmartHR is the JP authority, not just the palette.** It is a Japanese HR SaaS — the same product shape as ours, aimed at the same buyers — its library is open source, and it is the most actively maintained system of any measured here: **561 commits in 90 days**, last commit 2026-09-07 (Carbon: 418). It was already the colour source; this decision extends it to how a JP business screen behaves. **デジタル庁 (Digital Agency) is the standards reference.** Its design system is the closest thing Japan has to a public, government-backed baseline, and it is what a JP enterprise customer or procurement reviewer will cite. Use it to answer "which standard does this meet" (JIS X 8341-3), not for visual style. ### Japanese conventions this library already follows — now written down These were correct decisions with no recorded reason. They are load-bearing; do not "simplify" them toward a Latin default: - **`--line-height-body: 1.7`.** Japanese body text needs 1.7–2.0, not the Latin 1.5. Full-width kana and kanji fill the em box, so the same 1.5 that reads as airy in English reads as cramped in Japanese. `--line-height-normal: 1.5` remains for Latin-only runs. - **14px body.** The JP business-software norm, and it happens to agree with Carbon's `body-compact-01`. Do not raise it to a Western 16px default. - **A per-language font slot, not one merged stack.** `--font-sans-base` is deliberately a pure system stack so the library renders with zero font setup; Japanese arrives through `--font-sans-ja`, which `styles/base.css` wires to `[lang="ja"]`. Keep the indirection — merging a JP face into the base stack looks like a simplification and quietly removes the hook a consumer themes through. - **Density never touches type size.** `density.css` sets `--scaling` only; `font-size` appears **zero** times in it. This is the single most important rule for dense JP screens: Japanese loses legibility far faster than Latin when shrunk, because the strokes-per-em of a kanji do not survive it. Compress spacing to fit more on screen — never the characters. ## Compact without becoming ugly — the rules that hold both "Fit more on one screen" and "still looks composed" are not in tension if the compression is applied to the right axis: 1. **Compress spacing, never type.** See above. `--scaling` is the only density knob. 2. **Keep the ratio, shrink the unit.** The φ macro rhythm (`docs/SPACING.md`) stays intact under density because `--phi-unit` is itself a spacing token — the proportions between sections are preserved while the absolute gaps shrink. That is why density does not make the page look broken, only tighter. 3. **Density is a token axis, not a per-screen decision.** `data-density` on the root, three values. A screen that wants to be denser than `compact` is a screen with too much on it. 4. **The information ceiling is the row, not the page.** Dense JP admin screens get their density from row height and column count (`--table-cell-padding-y`, `--band-height-*`), not from squeezing the page gutter. Take row heights from SmartHR's tables. 5. **Touch targets do not participate in density.** See divergence 5 — this is currently violated. ## What this does NOT mean **We do not adopt Carbon's components.** There are 127 catalogued components here with 3,480 tests and a token contract that took #316/#319 to land. Swapping libraries would throw that away to buy guidance we can simply read. Carbon is the **specification authority**, not a dependency. **We do not adopt Carbon's colours or brand.** Colour stays SmartHR-anchored. Carbon owns geometry and rhythm; SmartHR owns hue. ## The open divergences Recorded rather than silently fixed, because each is a real decision: 1. **`--space-5` (20px) has no Carbon equivalent.** Carbon steps 16 → 24 on purpose: a scale with both 20 and 24 lets two authors space the same relationship differently. Either retire it or write down what it is for. Pinned by `src/tokens/__tests__/carbon-scale-alignment.test.ts`, which fails if a NEW off-scale step appears. 2. **The type scale diverges by construction.** Carbon uses integers — 12, 14, 16, 18, 20, 24, 28, 32, 36 — while `--font-size-ratio: 1.1227` (φ^¼) produces 11.1, 12.5, 17.6, 19.8, 22.2. Only the 14px body agrees. Fractional sizes do cost something measurable — they snap a line box half a pixel either way, which is ±0.5px of the residual in gh#370 — but they are not what that issue is. gh#370 is that `place-items: center` centres a LINE BOX and a line box is not a letterform; re-measured from the painted ink, the glyph classes' optical centres lie 0.21em apart (`g` 3.69px low in the 28px `md` box where `神`, `G` and `GX` are within 0.94px), so no glyph-blind rule centres them all — the best glyph-blind rule, `text-box: trim-both ex alphabetic`, still leaves 2.25px. So the correction moved up a layer: `Logo` classifies the glyph string it is handed into the ink band it occupies and CSS applies that band's offset, which measures 1.38px worst case and needs no `text-box` at all (`src/styles/logo-layout.css` carries the full matrix). Aligning the scale is a visual change to every screen, so it is a separate decision, not a side effect of this one. 3. **The large end is missing.** Carbon has 64/80/96/160px; this scale stops at 48px. Nothing needs them yet — add from Carbon's steps when something does, rather than inventing a number. 4. **2px (`spacing-01`) is missing.** Same rule: take Carbon's value if a hairline gap is ever needed. 5. **`--scaling` takes the whole scale off the 4px grid, and undercuts the 44px touch floor.** `density="compact"` sets `--scaling: 0.92`, so every step becomes fractional — 16px → 14.72px, 24px → 22.08px — and the grid Carbon's scale is built on only holds at default density. Worse, the coarse-pointer override in `tokens/components/control.css` raises controls to `--band-height-xl` (44px, "rule #24"), but `--control-height` multiplies it by `--scaling` anyway: **44 × 0.92 = 40.48px on a touch device at compact density.** That still clears WCAG 2.2 AA (24px), but it breaks this library's own rule #24. Carbon's answer to density is discrete size variants that stay on the grid, not a continuous multiplier — worth reconsidering. Verify on a real touch device before changing anything. 6. **Type scale vs Japanese rendering.** Divergence 2 is sharper for JP than for Latin: fractional sizes (12.5px, 17.6px, 19.8px) put full-width glyphs on half-pixel boundaries, where kanji strokes blur far more visibly than Latin letterforms. Another reason to prefer Carbon's integer steps if the scale is ever revisited. ## The PROP SURFACE of a component is antd's too, not just its group name antd was already the authority for which components exist and which group they live in. That answered "is there a Table" and never answered "what does a Table take". So every prop was decided here, one at a time, and the answer drifted per component: `DataTable` grew `pin: "end"` where antd has `fixed`, `sortable: true` where antd has `sorter`, and no answer at all for filters, expandable rows or a totals row — which is how a consumer ends up hand-rolling a `` and a sticky column in page CSS. **The rule: where antd names a capability, this library takes antd's name and antd's semantics.** > **Restated and widened by the repo owner on 2026-09-12, because the rule above was being read as > advice rather than as the standard it is: Ant Design IS the standard. A missing capability is > ported from antd 100% FIRST — its names, its props, its semantics — and improved afterwards. > Not redesigned first, and not half-ported.** > > Two things forced the restatement, both measured rather than felt: > > - `Dialog` + `AlertDialog` ship **26** exports with **12 name-for-name pairs and 0 parts unique > to `AlertDialog`**, whose entire difference is `role="alertdialog"` plus `isDismissable={false}` > — two props the shell already takes. antd has exactly one `Modal`, where danger is `okType` > and `Modal.confirm()`. The shape here came from Radix, silently, against this very rule > (gh#567). A package-wide sweep over all 272 public exports found this is the ONLY such pair: > `Skeleton.Avatar/Button/Input/Image/Node` looks identical in shape but is antd's own naming, > so it is compliance, not drift. > - Whole families arrived half-ported: Ant Design X without `Conversations`, `Attachments`, > `ThoughtChain`, `Welcome` or `Actions` (gh#559); `FloatButton` never at all (gh#558); > `Typography` reduced to `Text` + `Heading`, with `Paragraph`, `Link`, `copyable`, `editable`, > `mark`, `keyboard` and `italic` simply absent. > > A deviation from antd is still allowed — the three below are — but it must be WRITTEN DOWN at > the point of deviation. An undocumented deviation is a bug, and gh#567 is what that bug costs: > a consumer forced to pick between the right ARIA role and a form it needs, and an accessibility > decision pushed onto the party least able to make it. > The gap is read out of the INSTALLED types (`antd/es/table/interface.d.ts`, > `antd/es/table/InternalTable.d.ts` and the `@rc-component/table` interface they extend) — never > from memory, because antd's own names move between majors (`fixed: 'left'` is deprecated in favour > of `start` inside rc-table itself). > Đọc sau 20.0.0: bản major ấy đã **gỡ `antd` khỏi devDependencies** cùng máy sinh màu của nó, và > `check:no-antd-runtime` canh cho nó không quay lại. Câu trên mô tả cách bề mặt prop này ĐƯỢC ĐỌC > lúc antd còn cài, không phải một lời mời cài lại. Lần sau muốn đối chiếu, đọc type ở một checkout > riêng rồi ghi số hiệu bản vào đây — đừng thêm dependency. **Three things override antd's spelling, each for a stated reason:** - **Logical over physical.** antd's `fixed: 'left' | 'right'` cannot mirror for an RTL locale, so only `start` / `end` are published. Same rule that makes `check:rtl` a gate. Table `pagination.position` follows it (gh#705): antd `topLeft | topCenter | topRight | bottomLeft | bottomCenter | bottomRight | none` is `topStart | topCenter | topEnd | bottomStart | bottomCenter | bottomEnd | none` (`TablePaginationPositionProp`, default `['bottomEnd']`), the camelCase shape `DropdownMenuPlacementProp` already uses. antd's `size="small"` Table → small pager is `density="compact"` → `Pagination size="sm"`. - **This library's controlled vocabulary wins on values.** antd's `SortOrder` is `'ascend' | 'descend'`; here it stays `SortDirectionProp` (`asc` / `desc`), because that type already exists and a second spelling of the same axis is exactly what `check:prop-vocabulary` exists to prevent. - **A capability this library already has keeps its own name.** antd's `size` (`small | middle | large`) IS `density` (`compact | default | comfortable`); antd's `locale` IS the `t()` layer. Adding the antd spelling as an alias would be duplication, not parity. - **`SegmentedOption.count`.** antd's `SegmentedItemType` has no count field — consumers embed counts in `label`. Nested `Badge` `secondary` is `--muted`, which matches the Segmented track (gh#602, measured 1.00:1). This library adds `count` / `overflowCount` / `showZero` / `countLabel` on `SegmentedOption` with a DS-owned pill (`--segmented-count-*` tokens), same counter vocabulary as `Button` / `Toggle`. - **`DraggablePanel.labels`.** antd's Draggable Modal demo has no i18n hook for the drag handle. Embedded consumers cannot mount `AppProvider` without writing theme attributes on the host `document.documentElement` (gh#606). `labels?: { close?: string; move?: string }` overrides `t()` per control; a scoped `AppProvider` subtree remains the long-term fix. - **`Badge.onRemove` instead of antd `Tag`'s `closable` + `onClose`.** Semantics match antd's closable tag (a chip that draws its own × and fires one callback). The boolean is folded into prop presence (`onRemove` omitted ⇒ no ×), and the callback is named `onRemove` rather than `onClose`, because `onClose` already means overlay dismiss across Dialog/Drawer and would read as closing a surface, not removing one applied filter chip. Implemented on `Badge` — the DS chip primitive — rather than adding a separate `Tag` export beside `Badge`. - **`ChatComposer.submitType="modEnter"` and `ChatComposer.allowEmptySubmit`.** Ant Design X `Sender.submitType` is only `"enter" | "shiftEnter"`, and `Sender` never submits an empty draft. A comment composer on a record needs the convention GitHub, Jira, Linear and GitLab share — `Enter` breaks the line, `⌘+Enter` (Apple platforms, `metaKey`) / `Ctrl+Enter` (elsewhere, `ctrlKey`) sends — and needs to post a status change with no text (gh#693). `"modEnter"` extends antd's union rather than renaming it, so both antd values keep their meaning; its hint is `dataEntry.chatComposer.hintModEnter` with `{modifier}` from `isApplePlatform()` (`@godxjp/ui/lib/utils`). `allowEmptySubmit` (default `false`, antd's behaviour) sends `""`, still never while `loading` / `disabled` / `readOnly`. - **`Table.striped` / `DataTable.striped` (gh#700).** antd names no zebra capability — its docs stripe through `rowClassName` — so there is no antd spelling to port. Element Plus calls it `stripe`, Bootstrap `.table-striped`, MUI documents `:nth-of-type(odd)`. This library takes `striped`: a positive boolean adjective, the shape `bordered` and `hoverable` already have on the same component, and the spelling `DataTable` had shipped since 17f4a067. It is TRI-STATE on purpose: omitted inherits the service default `--table-row-striped-alpha` (`0%` at `:root`, so one theme line — `:root { --table-row-striped-alpha: 100%; }` — stripes every list table), `true` / `false` override it per table. `rowClassName` is not the answer here: it counts DOM rows, so an expanded detail row shifts every stripe after it, and `ui-audit` blocks the utilities it would need. - **`Masonry.gap` is antd `gutter`, and its breakpoint steps are this library's (gh-masonry port).** Three divergences on one component, each for a reason already written down elsewhere in this file: 1. **`gutter` → `gap`.** antd's `gutter` takes a raw pixel number (or a per-breakpoint map of them). This library already owns that axis under the name `gap` on `Flex`, `ResponsiveGrid` and `AuthStack`, `check:prop-vocabulary` maps a field called `gap` to `GapProp`, and a token step is what makes spacing follow `--scaling` (density) and a tenant theme. "This library's controlled vocabulary wins on values" is the rule; here it wins on the name too, because the name and the value type move together. antd's tuple `[Gap, Gap]` survives as `[GapProp, GapProp]` = `[inline, block]`. **`gutter` is not silently absent**: it is declared on the prop type as `never`, so a consumer arriving from antd's docs gets a compile error and a `@deprecated` hint naming `gap`, plus a development-time `console.warn`. 2. **`columns` steps are `base sm md lg xl`, not antd's `xs sm md lg xl xxl`.** antd's `xs` IS this library's `base` (the mobile-first floor), and a second spelling of one axis is what `check:prop-vocabulary` exists to prevent; `xxl` has no step here at all. `Flex direction` is the precedent shape and the media queries are literally the `--flex-direction-*` cascade's (sm 40rem · md 48rem · lg 64rem · xl 80rem). Both antd spellings FAIL LOUDLY — TypeScript rejects them as excess properties and the component names them in a development warning — because a silently-ignored `xs` is the worst outcome of the three. 3. **`MasonryItem.height` is HONOURED, where antd declares it and never reads it.** Verified in antd `master`: `Masonry.tsx` builds every `ItemHeightData` from `getBoundingClientRect()` alone, and all six demos carry their heights in `data`. Porting the field as inert would ship a documented prop that does nothing. Here a finite `height` sizes the tile and replaces its measurement, which is also what lets a first paint and an SSR render land in the right place. Not ported, each under a rule that already exists: `classNames` / `styles` (a knob only a fork could reach — `src/tokens/components/masonry.css` is the answer), `prefixCls` / `rootClassName` (no `prefixCls` layer here), and rc-motion's tile-REMOVAL animation (the arrival fade and the re-flow slide are ported in CSS and both snap under `prefers-reduced-motion`). `fresh` keeps antd's name and antd's `false` default even though `docs/roadmap/list-masonry.md` (2026-09-10) proposed renaming it `observeItems` and defaulting it on — that proposal predates the 2026-09-12 restatement above, and "the antd name says nothing" is exactly the reasoning the restatement rejects. The same roadmap's invented `sequential` prop is not ported for the same reason: antd has no such knob, and improvements come after parity, not instead of it. - **`Affix` and `Anchor` take the LOGICAL axis where antd takes the physical one (gh#827/gh#828).** Ported from `ant-design@master`, read out of `components/affix/{index.tsx,utils.ts}` and `components/anchor/{Anchor,AnchorLink}.tsx` on 2026-09-21, not out of the docs tables. Every antd prop is present. Four renames, and nothing else: 1. **`offsetTop` → `offsetBlockStart`, `offsetBottom` → `offsetBlockEnd`** (both components; `Anchor.targetOffset` → `targetOffsetBlockStart` with it). `check:rtl` exists to keep `inset-block-start` out of `top`'s hands in every stylesheet here, and a prop that names a physical edge re-opens that door at the API. It is also load-bearing rather than cosmetic: the offset is a CSS custom property (`--affix-inset-block-start`), read once by the sentinel that detects the crossing and once by the pinned bar that paints it, so the name has to be the one CSS uses. All three antd spellings are declared `never` — a compile error carrying an `@deprecated` hint that names the replacement — plus a development `console.warn`, plus the MCP catalog entry. The `Masonry gutter → gap` precedent, applied to a second component. 2. **`Anchor.onChange` → `onValueChange`,** beside new `value` / `defaultValue`. The active `href` is a controlled value and this library has one spelling for that. antd has no controlled form of it at all (`getCurrentAnchor` is a transform of the computed answer, not a value), so this is an ADDITION with a rename attached rather than a substitution, and `getCurrentAnchor` is ported unchanged beside it — a controlled `value` simply outranks it. antd's own note is ported too: `onValueChange` reports the link the SCROLL POSITION resolved, not the one `getCurrentAnchor` substituted. **`Affix.onChange` is NOT renamed**, and the distinction is the point: there is no pinned VALUE to control, only an observation of a derived boolean, so no triad applies. `Attachments.onChange` and `ActionsFeedback.onChange` already carry antd's name with a non-DOM payload for the same reason. **Not ported, each under a rule that already exists:** `classNames` / `styles` on `Anchor` (a knob only a fork could reach — `src/tokens/components/anchor.css` is the answer), `prefixCls` / `rootClassName`, and antd's deprecated `Anchor children` / `Anchor.Link` JSX form (antd itself warns on it and says to use `items`). **One deliberate behavioural difference, in `Anchor`.** antd resolves from scroll position on mount unconditionally, which overwrites a landing hash on any page whose hashed section happens to be above the fold. Here the hash is read in the state INITIALISER and the mount resolution is skipped when it matched, so `/page#section` is correct on the first render with no scroll event ever firing — which is gh#828's acceptance criterion, and the one place antd's behaviour is worse rather than merely differently named. **Two things antd does not have at all**, both required by the contract rather than invented: `Anchor.label` (antd ships an unnamed `
`; a `