@design-ai/cli 4.55.0

package/knowledge/design-tokens/ant-design.md

@@ -0,0 +1,124 @@
+---
+title: Ant Design seed tokens
+source: refs/ant-design/components/theme/themes/seed.ts
+upstream: https://github.com/ant-design/ant-design/blob/master/components/theme/themes/seed.ts
+extracted_at: 2026-05-19
+applies_to: [react, antd, design-system]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Ant Design seed tokens
+
+Ant Design uses a layered token model: **seed tokens** (raw inputs) → **map tokens** (derived scales) → **alias tokens** (semantic names). This file documents the seed layer — the inputs you change to retheme the entire system.
+
+## Color seeds
+
+| Token | Value |
+| --- | --- |
+| `colorPrimary` | `'#1677ff'` |
+| `colorSuccess` | `'#52c41a'` |
+| `colorWarning` | `'#faad14'` |
+| `colorError` | `'#ff4d4f'` |
+| `colorInfo` | `'#1677ff'` |
+| `colorLink` | `''` |
+| `colorTextBase` | `''` |
+| `colorBgBase` | `''` |
+
+
+## Preset palette anchors
+
+Ant Design ships 12 preset color families. Each anchor below is the "primary" hue (rank 6 in a 10-step scale). The full ramp is generated at runtime by `genPresetColor`.
+
+| Name | Hex | Swatch |
+| --- | --- | --- |
+| blue | `#1677FF` | <span aria-hidden="true" style="display:inline-block;width:0.875rem;height:0.875rem;border-radius:999px;border:1px solid rgba(0,0,0,.18);vertical-align:-0.125em;background-color:#1677FF;"></span> |
+| purple | `#722ED1` | <span aria-hidden="true" style="display:inline-block;width:0.875rem;height:0.875rem;border-radius:999px;border:1px solid rgba(0,0,0,.18);vertical-align:-0.125em;background-color:#722ED1;"></span> |
+| cyan | `#13C2C2` | <span aria-hidden="true" style="display:inline-block;width:0.875rem;height:0.875rem;border-radius:999px;border:1px solid rgba(0,0,0,.18);vertical-align:-0.125em;background-color:#13C2C2;"></span> |
+| green | `#52C41A` | <span aria-hidden="true" style="display:inline-block;width:0.875rem;height:0.875rem;border-radius:999px;border:1px solid rgba(0,0,0,.18);vertical-align:-0.125em;background-color:#52C41A;"></span> |
+| magenta | `#EB2F96` | <span aria-hidden="true" style="display:inline-block;width:0.875rem;height:0.875rem;border-radius:999px;border:1px solid rgba(0,0,0,.18);vertical-align:-0.125em;background-color:#EB2F96;"></span> |
+| pink | `#EB2F96` | <span aria-hidden="true" style="display:inline-block;width:0.875rem;height:0.875rem;border-radius:999px;border:1px solid rgba(0,0,0,.18);vertical-align:-0.125em;background-color:#EB2F96;"></span> |
+| red | `#F5222D` | <span aria-hidden="true" style="display:inline-block;width:0.875rem;height:0.875rem;border-radius:999px;border:1px solid rgba(0,0,0,.18);vertical-align:-0.125em;background-color:#F5222D;"></span> |
+| orange | `#FA8C16` | <span aria-hidden="true" style="display:inline-block;width:0.875rem;height:0.875rem;border-radius:999px;border:1px solid rgba(0,0,0,.18);vertical-align:-0.125em;background-color:#FA8C16;"></span> |
+| yellow | `#FADB14` | <span aria-hidden="true" style="display:inline-block;width:0.875rem;height:0.875rem;border-radius:999px;border:1px solid rgba(0,0,0,.18);vertical-align:-0.125em;background-color:#FADB14;"></span> |
+| volcano | `#FA541C` | <span aria-hidden="true" style="display:inline-block;width:0.875rem;height:0.875rem;border-radius:999px;border:1px solid rgba(0,0,0,.18);vertical-align:-0.125em;background-color:#FA541C;"></span> |
+| geekblue | `#2F54EB` | <span aria-hidden="true" style="display:inline-block;width:0.875rem;height:0.875rem;border-radius:999px;border:1px solid rgba(0,0,0,.18);vertical-align:-0.125em;background-color:#2F54EB;"></span> |
+| gold | `#FAAD14` | <span aria-hidden="true" style="display:inline-block;width:0.875rem;height:0.875rem;border-radius:999px;border:1px solid rgba(0,0,0,.18);vertical-align:-0.125em;background-color:#FAAD14;"></span> |
+| lime | `#A0D911` | <span aria-hidden="true" style="display:inline-block;width:0.875rem;height:0.875rem;border-radius:999px;border:1px solid rgba(0,0,0,.18);vertical-align:-0.125em;background-color:#A0D911;"></span> |
+
+
+## Typography
+
+| Token | Value |
+| --- | --- |
+| `fontFamily` | ``-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial` |
+| `fontFamilyCode` | ``'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, Courier, monospace`` |
+| `fontSize` | `14` |
+
+
+## Motion (cubic-bezier curves)
+
+| Token | Value |
+| --- | --- |
+| `motionUnit` | `0.1` |
+| `motionBase` | `0` |
+| `motionEaseOutCirc` | `'cubic-bezier(0.08, 0.82, 0.17, 1)'` |
+| `motionEaseInOutCirc` | `'cubic-bezier(0.78, 0.14, 0.15, 0.86)'` |
+| `motionEaseOut` | `'cubic-bezier(0.215, 0.61, 0.355, 1)'` |
+| `motionEaseInOut` | `'cubic-bezier(0.645, 0.045, 0.355, 1)'` |
+| `motionEaseOutBack` | `'cubic-bezier(0.12, 0.4, 0.29, 1.46)'` |
+| `motionEaseInBack` | `'cubic-bezier(0.71, -0.46, 0.88, 0.6)'` |
+| `motionEaseInQuint` | `'cubic-bezier(0.755, 0.05, 0.855, 0.06)'` |
+| `motionEaseOutQuint` | `'cubic-bezier(0.23, 1, 0.32, 1)'` |
+| `motion` | `true` |
+
+
+## Sizing
+
+| Token | Value |
+| --- | --- |
+| `sizeUnit` | `4` |
+| `sizeStep` | `4` |
+| `sizePopupArrow` | `16` |
+| `controlHeight` | `32` |
+
+
+## Border / radius
+
+| Token | Value |
+| --- | --- |
+| `borderRadius` | `6` |
+
+
+## Lines
+
+| Token | Value |
+| --- | --- |
+| `lineWidth` | `1` |
+| `lineType` | `'solid'` |
+
+
+## Notes for designers
+
+- `colorPrimary` drives the entire interactive surface — buttons, links, focus rings, selected states.
+- `borderRadius: 6` is the system default. Components like `Button` and `Input` use this directly. Going to `0` produces the "wireframe" aesthetic; going to `12+` produces "soft/friendly".
+- `controlHeight: 32` is the canonical input height. `controlHeightSM = controlHeight - 8 = 24`, `controlHeightLG = controlHeight + 8 = 40`. Match this when building custom controls so they align in forms.
+- `sizeUnit: 4, sizeStep: 4` produces the spacing scale `4, 8, 12, 16, 20, 24, 32, 40, 48, 64`.
+- Motion easings: `motionEaseOut` for entering UI, `motionEaseInOut` for sliding, `motionEaseOutCirc` for slide-up overlays.
+
+## How to use this in a project
+
+If your project uses `antd`, set `theme.token` directly:
+
+```tsx
+<ConfigProvider theme={ token: { colorPrimary: '#7C3AED', borderRadius: 8 } }>
+  <App />
+</ConfigProvider>
+```
+
+If your project does not use `antd` but you want the same ramp model:
+
+1. Pick a primary hex.
+2. Use `tools/extractors/preset_color_ramp.py` (TODO) to generate the 10-step ramp.
+3. Map ramps to semantic aliases (`color-primary`, `color-primary-hover`, …) using ranks `6/5/7` for default/hover/active.

package/knowledge/design-tokens/material-3.md

@@ -0,0 +1,235 @@
+<!-- hand-written -->
+---
+title: Material Design 3 token reference
+applies_to: [material-design, hct, design-tokens, android, web]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Material Design 3 (Material You)
+
+Google's third-generation Material Design (2021+). Token-first, **HCT-based** color system, dynamic theming. The reference for Android UIs and many web product systems.
+
+If your product targets Android primarily or aligns with Material aesthetic, build on this. For non-Material products, learn it as comparison.
+
+## What changed from Material 2
+
+| Aspect | Material 2 (2018) | Material 3 (2021+) |
+| --- | --- | --- |
+| Color | RGB-based palette | HCT-based, dynamic from seed |
+| Tokens | Limited semantic tokens | Full token system (color, type, motion, shape) |
+| Customization | Theme provider with overrides | Generate full theme from one seed color |
+| Dynamic theming | None | Yes (Android system color, user wallpaper) |
+| Surface model | Elevation overlays | Surface + tonal containers |
+| Buttons | All-caps text on Filled | Mixed-case (modernized) |
+
+## Color: HCT and tonal palettes
+
+**HCT** = Hue, Chroma, Tone. Tonal palettes generate 13 stops per hue from one seed:
+
+```
+Tone:  0   5   10  20  30  40  50  60  70  80  90  95  99  100
+       └──────────────────── one tonal palette ────────────────────┘
+       darkest                                                lightest
+```
+
+Tone is roughly equivalent to OKLCH `L`, but tuned for Material's perceptual model.
+
+### Five tonal palettes (per theme)
+
+| Palette | Source |
+| --- | --- |
+| **Primary** | The brand seed |
+| **Secondary** | Hue ~rotated; lower chroma |
+| **Tertiary** | Different hue (often complement) |
+| **Neutral** | Slightly chromatic gray, matched to primary's hue |
+| **Neutral-variant** | Slightly more chromatic neutral |
+
+Plus **error** as a fixed red tonal palette.
+
+### Token roles (canonical)
+
+```
+Light theme:
+  primary               = primary tone 40
+  on-primary            = primary tone 100 (white)
+  primary-container     = primary tone 90
+  on-primary-container  = primary tone 10
+
+  surface               = neutral tone 99
+  on-surface            = neutral tone 10
+  surface-container     = neutral tone 94
+  surface-container-high = neutral tone 92
+  surface-container-highest = neutral tone 90
+  outline               = neutral-variant tone 50
+  outline-variant       = neutral-variant tone 80
+
+  background            = neutral tone 99
+  on-background         = neutral tone 10
+
+  inverse-surface       = neutral tone 20
+  inverse-on-surface    = neutral tone 95
+  inverse-primary       = primary tone 80
+
+  error                 = error tone 40
+  on-error              = error tone 100
+  error-container       = error tone 90
+  on-error-container    = error tone 10
+```
+
+For dark theme: tones flip. `primary` = primary tone 80, `on-primary` = primary tone 20, etc.
+
+### Why containers?
+
+Material 3's "container" concept is its main innovation. Instead of "primary + on-primary" only, you also have "primary-container + on-primary-container":
+
+- `primary` (tone 40 light) — the FAB, the most-emphasized button
+- `primary-container` (tone 90 light) — secondary surface that uses brand color subtly
+
+This means: the FAB is bold primary; a "Premium" badge can sit on `primary-container` without competing.
+
+## Typography
+
+Material 3's type scale is more refined than Material 2's:
+
+| Role | Size | Weight | Line height | Letter spacing |
+| --- | --- | --- | --- | --- |
+| **Display Large** | 57px | 400 | 64px | -0.25px |
+| **Display Medium** | 45px | 400 | 52px | 0 |
+| **Display Small** | 36px | 400 | 44px | 0 |
+| **Headline Large** | 32px | 400 | 40px | 0 |
+| **Headline Medium** | 28px | 400 | 36px | 0 |
+| **Headline Small** | 24px | 400 | 32px | 0 |
+| **Title Large** | 22px | 400 | 28px | 0 |
+| **Title Medium** | 16px | 500 | 24px | 0.15 |
+| **Title Small** | 14px | 500 | 20px | 0.1 |
+| **Label Large** | 14px | 500 | 20px | 0.1 |
+| **Label Medium** | 12px | 500 | 16px | 0.5 |
+| **Label Small** | 11px | 500 | 16px | 0.5 |
+| **Body Large** | 16px | 400 | 24px | 0.5 |
+| **Body Medium** | 14px | 400 | 20px | 0.25 |
+| **Body Small** | 12px | 400 | 16px | 0.4 |
+
+Roboto is the default; Material 3 also has **Roboto Flex** (variable font) and **Roboto Serif** for serif variants.
+
+For Korean: pair with Pretendard or Noto Sans KR; see [`i18n/korean-typography.md`](../i18n/korean-typography.md).
+
+### Material 3 dropped uppercase buttons
+
+Material 2's `text-transform: uppercase` on buttons is gone. Material 3 uses sentence case, which reads cleaner with non-Latin scripts.
+
+## Shape (corner radius scale)
+
+Material 3 standardizes corner radius via tokens:
+
+| Token | Radius |
+| --- | --- |
+| `shape-corner-none` | 0 |
+| `shape-corner-extra-small` | 4 |
+| `shape-corner-small` | 8 |
+| `shape-corner-medium` | 12 |
+| `shape-corner-large` | 16 |
+| `shape-corner-extra-large` | 28 |
+| `shape-corner-full` | 9999 (pill) |
+
+Each component has a default shape. Buttons: `extra-small` (4) for outlined, `full` for FAB.
+
+Material 3 also introduces **shape morphing** — components can transition between shapes (e.g., FAB to bottom sheet expanding).
+
+## Motion — Easing & Duration
+
+Material 3 standardizes motion via two axes:
+
+### Easing
+
+| Token | Curve | Use |
+| --- | --- | --- |
+| `motion-easing-linear` | linear | Loading spinners |
+| `motion-easing-standard` | `cubic-bezier(0.2, 0, 0, 1)` | Default — entering/exiting |
+| `motion-easing-emphasized` | `cubic-bezier(0.2, 0, 0, 1)` | Emphasis on primary motion |
+| `motion-easing-emphasized-decelerate` | `cubic-bezier(0.05, 0.7, 0.1, 1)` | Hero arrives |
+| `motion-easing-emphasized-accelerate` | `cubic-bezier(0.3, 0, 0.8, 0.15)` | Hero exits |
+
+### Duration
+
+Increments of 50ms from 50 to 600:
+
+| Token | Duration |
+| --- | --- |
+| `motion-duration-short1` | 50ms |
+| `motion-duration-short2` | 100ms |
+| `motion-duration-short3` | 150ms |
+| `motion-duration-short4` | 200ms |
+| `motion-duration-medium1` | 250ms |
+| `motion-duration-medium2` | 300ms |
+| `motion-duration-medium3` | 350ms |
+| `motion-duration-medium4` | 400ms |
+| `motion-duration-long1` | 450ms |
+| `motion-duration-long2` | 500ms |
+| `motion-duration-long3` | 550ms |
+| `motion-duration-long4` | 600ms |
+
+Aligns with our duration tiers in [`motion/principles.md`](../motion/principles.md).
+
+## Elevation (5 levels)
+
+| Level | Use |
+| --- | --- |
+| `elevation-0` | Surface, no shadow |
+| `elevation-1` | Card, FAB at rest |
+| `elevation-2` | Top app bar (scrolled), filled buttons elevated |
+| `elevation-3` | Modal, popover, navigation drawer |
+| `elevation-4` | Floating menu, picker |
+| `elevation-5` | Reserved (rarely used) |
+
+In dark mode, Material 3 uses **surface tint overlays** instead of just shadow — surfaces get progressively lighter tones to indicate elevation. This reads better on dark backgrounds.
+
+## State layers
+
+Material 3 introduces a "state layer" — a semi-transparent overlay applied to interactive elements on hover/focus/press. Universal across components:
+
+| State | Layer opacity (on top of base color) |
+| --- | --- |
+| Hover | 8% |
+| Focus | 12% |
+| Pressed | 12% |
+| Dragged | 16% |
+| Selected | 8% |
+
+Layer color matches `on-X` tokens (e.g., on a primary button, the state layer is `on-primary` at 8% opacity).
+
+This is the elegant unification — instead of writing per-component hover/focus styles, you apply one system.
+
+## Tools and extraction
+
+- **Material Theme Builder**: <https://material-foundation.github.io/material-theme-builder/> — paste a hex, get a full Material 3 token set.
+- **Material 3 Theme Editor for Figma**: official plugin for Figma users.
+- **m3-theme-editor**: VS Code extension for live editing.
+
+The Theme Builder is the canonical source. For consuming Material 3 tokens in code, export to:
+- CSS custom properties
+- W3C DTCG JSON (compatible with Style Dictionary)
+- Android XML (for Android apps)
+- iOS Swift (for iOS apps)
+
+## When to use Material 3
+
+- **Android-primary apps**: native fit; don't fight the OS.
+- **Multi-platform that wants Google-aligned aesthetic**: Material 3 is the "modern Google" look.
+- **Teams that want one seed → full theme**: Material's dynamic theming is the simplest "give me a theme" pipeline.
+
+## When NOT to use
+
+- **Brand wants distinctive, non-Material aesthetic**: Material's shape + motion patterns are recognizable. Customizing fights the system.
+- **Korean consumer market**: Material is widely accepted but Korean designs often have a denser, more Toss/Kakao-coded aesthetic.
+- **Web with very specific brand**: prefer Tailwind v4's flexibility — see [`tailwind-v4.md`](tailwind-v4.md).
+
+## Cross-reference
+
+- [`knowledge/colors/color-theory.md`](../colors/color-theory.md) — HCT vs OKLCH
+- [`knowledge/design-tokens/tailwind-v4.md`](tailwind-v4.md) — alternative web token system
+- [`knowledge/design-tokens/ant-design.md`](ant-design.md) — alternative for enterprise web
+- [`knowledge/colors/mui-palette-structure.md`](../colors/mui-palette-structure.md) — MUI's Material implementation (mostly Material 2 still)
+- [Material 3 official spec](https://m3.material.io/)
+- [Material Theme Builder](https://material-foundation.github.io/material-theme-builder/)

package/knowledge/design-tokens/polaris-and-carbon.md

@@ -0,0 +1,231 @@
+<!-- hand-written -->
+---
+title: Polaris (Shopify) and Carbon (IBM) — enterprise token references
+applies_to: [enterprise, b2b-saas, design-tokens]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Polaris and Carbon
+
+Two enterprise design systems worth knowing as references. Both prioritize accessibility + token-based theming. Useful for B2B SaaS / e-commerce admin / enterprise dashboards.
+
+## Polaris (Shopify)
+
+Optimized for **e-commerce admin** — merchant tools, multi-store management, dense product catalog UIs.
+
+### Color tokens
+
+Polaris uses **role-based naming** without hue families:
+
+```
+Surface tokens:
+  --p-color-bg                       (page background)
+  --p-color-bg-surface               (cards, panels)
+  --p-color-bg-surface-secondary     (subtle alternate)
+  --p-color-bg-fill                  (filled inputs, switches)
+  --p-color-bg-fill-brand            (primary CTA)
+  --p-color-bg-fill-success
+  --p-color-bg-fill-warning
+  --p-color-bg-fill-critical
+
+Text tokens:
+  --p-color-text                     (primary)
+  --p-color-text-secondary
+  --p-color-text-disabled
+  --p-color-text-brand
+  --p-color-text-success
+  --p-color-text-warning
+  --p-color-text-critical
+
+Border tokens:
+  --p-color-border                   (default)
+  --p-color-border-secondary
+  --p-color-border-brand
+  --p-color-border-disabled
+```
+
+The `-fill` / `-text` / `-border` suffix pattern is consistent across colors. **Critical** is Polaris's term for "destructive/error" — note the slight rename from typical "error".
+
+### Typography
+
+```
+font-size-50:  10px (caption)
+font-size-75:  12px (small body)
+font-size-100: 13px (default body)
+font-size-200: 14px
+font-size-300: 16px (heading-md)
+font-size-400: 20px
+font-size-500: 24px (heading-lg)
+font-size-600: 30px
+font-size-700: 36px
+font-size-800: 48px (display)
+```
+
+Numeric naming (`-100`, `-200`) instead of `-sm`/`-md`/`-lg` is a Polaris signature — easier to insert intermediate values.
+
+### Spacing
+
+```
+space-025: 1px
+space-050: 2px
+space-100: 4px
+space-150: 6px
+space-200: 8px
+space-300: 12px
+space-400: 16px
+space-500: 20px
+space-600: 24px
+space-800: 32px
+space-1000: 40px
+space-1200: 48px
+space-1600: 64px
+space-2000: 80px
+space-2400: 96px
+space-3200: 128px
+```
+
+`-100` = 4px (the smallest non-pixel unit). Numeric naming + clear progression.
+
+### Notable patterns from Polaris
+
+- **`Page` and `Layout` primitives** with sections and slots — extremely opinionated layout system for admin screens
+- **`IndexTable`** — polaris's data table, optimized for admin lists with bulk actions
+- **`Filters` and `Tabs`** — admin search/filter patterns
+
+For admin dashboards: study Polaris's "Page → Layout → Card" composition. It's a strong template.
+
+### When to look at Polaris
+
+- Building Shopify apps (mandatory).
+- B2B SaaS admin UIs where Polaris's density + structure fits.
+- Token naming inspiration (numeric scales, role-based).
+
+## Carbon (IBM)
+
+Optimized for **enterprise data UIs** — analytics, dashboards, data manipulation tools (Cloud Pak, Watson, etc.).
+
+### Color tokens
+
+Carbon's tokens are role-based with a **theme-aware** layer:
+
+```
+Each Carbon theme (white, g10, g90, g100) has its own token values:
+
+Layer tokens (page → modal stacking):
+  --cds-background          (page bg)
+  --cds-layer               (first card)
+  --cds-layer-accent        (alt card variant)
+  --cds-layer-02            (2nd-level card on layer 1)
+  --cds-layer-03            (3rd-level card on layer 2)
+
+Text tokens:
+  --cds-text-primary
+  --cds-text-secondary
+  --cds-text-placeholder
+  --cds-text-on-color
+  --cds-text-helper
+  --cds-text-error
+
+Interactive tokens:
+  --cds-interactive          (primary brand)
+  --cds-link-primary
+  --cds-link-primary-hover
+  --cds-link-secondary
+  --cds-button-primary
+  --cds-button-secondary
+  --cds-button-tertiary
+  --cds-button-disabled
+
+Support tokens:
+  --cds-support-success
+  --cds-support-warning
+  --cds-support-error
+  --cds-support-info
+```
+
+The **layer system** is Carbon's standout: depth is encoded as `layer` / `layer-02` / `layer-03`. A modal on a card on a page automatically resolves to the right surface color.
+
+### Typography (IBM Plex)
+
+Default font: **IBM Plex Sans** (custom designed for Carbon).
+
+Type scale (Productive expressive):
+```
+caption-01:    12px / 16px
+helper-text:   12px / 16px
+body-compact:  14px / 18px
+body-01:       14px / 20px
+body-02:       16px / 24px
+heading-01:    14px / 18px / 600 weight
+heading-02:    16px / 22px / 600 weight
+heading-03:    20px / 28px / 400 weight
+heading-04:    28px / 36px / 400 weight
+heading-05:    32px / 40px / 400 weight
+heading-06:    42px / 50px / 300 weight
+heading-07:    54px / 64px / 300 weight
+display-01:    42px / 50px / 300 weight
+```
+
+"Productive" mode is dense; "Expressive" mode is more spacious — Carbon ships both.
+
+### Spacing
+
+```
+spacing-01: 0.125rem (2px)
+spacing-02: 0.25rem  (4px)
+spacing-03: 0.5rem   (8px)
+spacing-04: 0.75rem  (12px)
+spacing-05: 1rem     (16px)
+spacing-06: 1.5rem   (24px)
+spacing-07: 2rem     (32px)
+spacing-08: 2.5rem   (40px)
+spacing-09: 3rem     (48px)
+spacing-10: 4rem     (64px)
+spacing-11: 5rem     (80px)
+spacing-12: 6rem     (96px)
+spacing-13: 10rem    (160px)
+```
+
+### Notable patterns from Carbon
+
+- **DataTable** — heavy data tables with selection, batch actions, customizable density
+- **UI Shell** — the navigation chrome (header + side nav)
+- **Notification (toast/inline)** — typed for business contexts
+- **DataVisualization** library — Carbon Charts, focused on enterprise reporting
+
+### When to look at Carbon
+
+- Enterprise B2B with heavy data/dashboard content.
+- IBM ecosystem.
+- When dense, "professional" aesthetic is required (no playfulness).
+
+## Comparison
+
+| Aspect | Polaris | Carbon | (vs Material 3) | (vs Tailwind v4) |
+| --- | --- | --- | --- | --- |
+| Token naming | Role-based, numeric scales | Role-based, layer-aware | Role-based, container-pattern | Hue-based, numeric steps |
+| Audience | E-commerce admin | Enterprise / data | Cross-platform consumer | Web product (any) |
+| Density default | Comfortable | Productive (dense) | Comfortable | Comfortable |
+| Color generation | Hand-curated | Hand-curated | Generated from seed (HCT) | Generated from seed (OKLCH) |
+| Accessibility | High | Highest (IBM is strict) | High | Good (OKLCH helps) |
+| Customization | Token override | Token override per-theme | Whole theme from seed | Token override |
+
+## When to NOT use these directly
+
+For most teams: **don't import Polaris or Carbon directly**. They're heavy dependencies designed for the parent companies' ecosystems.
+
+- Use Polaris if building Shopify apps.
+- Use Carbon if you're IBM-aligned.
+- Otherwise: **learn from their token structures** but build your own (or use Tailwind / Ant / shadcn) and apply naming patterns you like.
+
+## Cross-reference
+
+- [`knowledge/design-tokens/tailwind-v4.md`](tailwind-v4.md) — modern web default
+- [`knowledge/design-tokens/material-3.md`](material-3.md) — Google's system
+- [`knowledge/design-tokens/ant-design.md`](ant-design.md) — alternative enterprise system
+- [`knowledge/colors/mui-palette-structure.md`](../colors/mui-palette-structure.md) — Material 2 still in MUI
+- [`docs/TOKEN-SYNC.md`](../../docs/TOKEN-SYNC.md) — three-tier architecture
+- [Polaris](https://polaris.shopify.com/)
+- [Carbon Design System](https://carbondesignsystem.com/)