@appsbd/vue3-appsbd-ui 1.0.1 → 1.0.3

package/design-system.md

@@ -1,403 +1,403 @@
-# Appsbd UI Library — Design System
-
-**AI Assistant Instructions**:
-This document is the **visual-language counterpart** to [AI_REFERENCE.md](./AI_REFERENCE.md). Where `AI_REFERENCE.md` documents component **APIs** (props, events, slots), this file documents the **design tokens** (colors, typography, spacing, radii, shadows, motion) that those components are built on. Use this file when you need to:
-
-- Pick the right color, font size, radius, or spacing for new UI
-- Style custom layouts that should feel consistent with built-in `Ab*` components
-- Theme the library (light/dark, brand re-skinning)
-- Translate a Figma mock from the Appsbd Design System to library code
-
-**Source of truth.** The visual foundations below are derived from the **Appsbd Design System** folder (`./Appsbd Design System/`) — itself extracted from the **"Kigen design system"** Figma file. The library implements these tokens in SCSS using the `bb-` CSS-variable prefix and the `.apbd-` class prefix. Where a design-system token has a direct library variable, both names are listed.
-
----
-
-## 1. Design Philosophy
-
-The library follows four rules, in priority order:
-
-1. **Bootstrap variables first.** If a need can be met by overriding a Bootstrap CSS variable (e.g. `--bb-primary`, `--bb-border-radius`), do that.
-2. **Custom tokens second.** When Bootstrap has no matching variable (skeletons, sliders, custom panels), define a new token in `src/styles/_variables.scss` using the **`apbd-`** namespace under the **`bb-`** prefix, e.g. `--bb-apbd-bg-color`.
-3. **Class-variant over new component.** Layout variations of an existing base component (e.g. `tile-card`, `item-card`, `insight-card` for `AbCard`) are **CSS class extensions** in the corresponding `_component.scss`, not new SFCs.
-4. **Dark-mode safe colors.** Use `var(--bb-apbd-bg-color)` and `var(--bb-apbd-border-color)` inside component styles instead of `body-bg` or `border-color`, so light/dark switching just works.
-
-> **Prefix rule.** CSS **class names** use `.apbd-` (e.g. `.apbd-skeleton`). CSS **variables** use `#{$prefix}` interpolation (e.g. `var(--#{$prefix}apbd-border-color)`, which compiles to `var(--bb-apbd-border-color)`).
-
----
-
-## 2. Brand & Color System
-
-### 2.1 Primary brand color
-
-The library's primary brand color is **Brand/600 — `#155EEF`** (Appsbd blue). It is the value of `--bb-primary` in the default (`blue`) skin and drives the focus ring, primary buttons, active nav, links, and component accents.
-
-### 2.2 Brand blue scale
-
-Used for primary actions, links, focus rings, active states.
-
-| Token       | Hex       | Library variable          | Usage                          |
-| ----------- | --------- | ------------------------- | ------------------------------ |
-| Brand/25    | `#F5F8FF` | —                         | Very light tint                |
-| Brand/50    | `#EFF4FF` | `--bb-primary-light`      | Active nav bg, light highlight |
-| Brand/100   | `#D1E0FF` | —                         | Hover tint                     |
-| Brand/200   | `#B2CCFF` | —                         | Border on blue tint            |
-| Brand/300   | `#84ADFF` | `--bb-apbd-border-color-focus` | Focus ring (light)        |
-| Brand/400   | `#528BFF` | —                         | Secondary interactive          |
-| Brand/500   | `#2970FF` | (dark-mode `--bb-primary`) | Hover on primary              |
-| **Brand/600** | **`#155EEF`** | **`--bb-primary` (light)** | **Primary action, brand blue** |
-| Brand/700   | `#004EEB` | `--bb-primary-btn-hover`  | Pressed / hover-darkened       |
-| Brand/800   | `#0040C1` | —                         | Dark brand                     |
-| Brand/900   | `#00359E` | —                         | Very dark                      |
-| Brand/950   | `#002266` | —                         | Darkest                        |
-
-### 2.3 Neutral / gray scale
-
-Used for text, borders, surfaces, and dividers.
-
-| Token    | Hex       | Usage                          |
-| -------- | --------- | ------------------------------ |
-| Gray/25  | `#FCFCFD` | Subtle backgrounds             |
-| Gray/50  | `#F9FAFB` | Table headers, inputs          |
-| Gray/100 | `#F2F4F7` | Light backgrounds, subtle border |
-| Gray/200 | `#EAECF0` | Default dividers               |
-| Gray/300 | `#D0D5DD` | Borders                        |
-| Gray/400 | `#98A2B3` | Disabled, placeholder          |
-| Gray/500 | `#667085` | Muted text                     |
-| Gray/600 | `#475569` | Secondary text                 |
-| Gray/700 | `#344054` | Body text                      |
-| Gray/800 | `#1D2939` | Heading text                   |
-| Gray/900 | `#101828` | Primary text                   |
-
-### 2.4 Semantic colors
-
-Used by `AbBaseAlert`, `AbBadge`, `AbToast`, `AbButton variant`, form error states.
-
-| Role        | Background | Border    | Text/Icon | Solid     |
-| ----------- | ---------- | --------- | --------- | --------- |
-| **Success** | `#ECFDF3`  | `#ABEFC6` | `#085D3A` | `#00C950` |
-| **Error**   | `#FEF2F2`  | `#FECACA` | `#B91C1C` | `#FB2C36` |
-| **Warning** | `#FFFBEB`  | `#FDE68A` | `#92400E` | `#EEB004` |
-| **Info**    | `#EFF4FF`  | `#B2CCFF` | `#155EEF` | `#2970FF` |
-
-These map to Bootstrap's `--bb-success`, `--bb-danger`, `--bb-warning`, `--bb-info` variants used by `AbButton`'s `variant` prop and `AbBadge`'s `variant` prop.
-
-### 2.5 Surface & layout colors
-
-| Role               | Hex       | Library variable               |
-| ------------------ | --------- | ------------------------------ |
-| App shell bg       | `#EBEFF5` | (page wrapper)                 |
-| Card / panel       | `#FFFFFF` | `--bb-apbd-bg-color` (light)   |
-| Sidebar bg         | `#FFFFFF` | (`AbSidebar` root)             |
-| Topbar bg          | `#FFFFFF` |                                |
-| Table header bg    | `#F9FAFB` | (`AbTable` thead)              |
-| Input bg           | `#FFFFFF` |                                |
-| Active nav-item bg | `#EFF4FF` | `--bb-apbd-sidebar-item-active-bg` |
-
-> **Dark-mode rule.** Component styles must read from `var(--bb-apbd-bg-color)` / `var(--bb-apbd-border-color)` instead of hard-coding `#FFFFFF` / `#EAECF0`, so the values flip cleanly when `[data-bs-theme="dark"]` is set on the root.
-
-### 2.6 Borders
-
-| Role           | Hex       | Library variable               |
-| -------------- | --------- | ------------------------------ |
-| Default        | `#EAECF0` | `--bb-apbd-border-color`       |
-| Strong         | `#D5D7DA` | `--bb-apbd-border-color-strong` |
-| Subtle         | `#F2F4F7` | —                              |
-| Brand / focus  | `#155EEF` | `--bb-primary`                 |
-| Focus ring     | `#84ADFF` | `--bb-apbd-border-color-focus` |
-| Error          | `#FDA29B` | `--bb-apbd-input-error-border` |
-
-### 2.7 Theme skins
-
-The library ships **multiple color skins** under `playground/skins/themes/`. Each is a `_<name>.scss` partial defining `$theme-color`, `$theme-color-light`, `$theme-color-dark`, `$theme-color-hover`, and `$border-color-focus-light`, then re-emitting them as `--bb-primary`, `--bb-primary-light`, `--bb-primary-rgb`, etc.
-
-**Built-in skins:** `blue` (default), `black`, `cyan`, `gray`, `green`, `orange`, `pink`, `purple`, `red`, `violet`.
-
-Skin switching is wired through the `AbColorPicker` in the playground; use the **`add-theme-skin`** project skill to add a new skin so all five wiring steps (theme partial, skin wrapper, vite rollup entry, picker option, `toggleTheme` mapping) are applied consistently.
-
----
-
-## 3. Typography
-
-### 3.1 Font families
-
-| Role            | Family           | Library token (CSS) | Usage                                    |
-| --------------- | ---------------- | ------------------- | ---------------------------------------- |
-| **Sans (UI)**   | **Inter**        | `--font-sans`       | All body, labels, headings, form fields  |
-| Nav             | Geist            | `--font-nav`        | Sidebar nav items, app brand name        |
-| Display         | Inter            | `--font-display`    | Hero / marketing display text            |
-| Auth headings   | Inter Tight      | `--font-auth`       | Login / register screen titles           |
-| Mono            | Geist            | `--font-mono`       | `<code>`, mono helpers                   |
-
-`Inter` is the variable font shipped in `Appsbd Design System/fonts/`. `Geist` and `Inter Tight` come from Google Fonts.
-
-### 3.2 Display scale
-
-For marketing pages, dashboards' hero numbers, and landing screens.
-
-| Style          | Size | Weight | Line height | Token                          |
-| -------------- | ---- | ------ | ----------- | ------------------------------ |
-| Display 2xl    | 72px | 700    | 1.0         | `--text-display-2xl-*`         |
-| Display xl     | 60px | 600    | 1.1         | `--text-display-xl-*`          |
-| Display lg     | 48px | 600    | 1.1         | `--text-display-lg-*`          |
-| Display md     | 44px | 600    | 1.15        | `--text-display-md-*`          |
-| Display sm     | 30px | 600    | 1.2         | `--text-display-sm-*`          |
-| Display xs     | 24px | 600    | 1.2         | `--text-display-xs-*`          |
-
-### 3.3 Text scale
-
-For app body, labels, captions.
-
-| Style    | Size | Weight | Line height | Library variable                     | Usage                  |
-| -------- | ---- | ------ | ----------- | ------------------------------------ | ---------------------- |
-| Text xl  | 20px | 400    | 30px        | `--bb-apbd-fs-lg` (1.5rem)           | Large body, subheaders |
-| Text lg  | 18px | 400    | 28px        | —                                    | Subheadings            |
-| Text md  | 16px | 400    | 24px        | `--bb-apbd-fs-md` (1rem)             | Body text (default)    |
-| Text sm  | 14px | 400    | 20px        | `--bb-apbd-fs-sm` (0.875rem)         | Labels, nav, hints     |
-| Text xs  | 12px | 400    | 16px        | `--bb-apbd-fs-xs` (0.75rem)          | Captions, meta         |
-| Text xxs | 11px | 400    | 14px        | —                                    | Micro labels           |
-
-### 3.4 Font weights
-
-| Token  | Weight | Library variable              |
-| ------ | ------ | ----------------------------- |
-| Thin   | 300    | `--bb-apbd-fw-thin`           |
-| Normal | 400    | `--bb-apbd-fw-normal`         |
-| Bold   | 500    | `--bb-apbd-fw-bold` (medium)  |
-| Bolder | 600    | `--bb-apbd-fw-bolder` (semi)  |
-| Boldest| 700    | `--bb-apbd-fw-boldest`        |
-
-### 3.5 Semantic type helpers
-
-These class names exist in `Appsbd Design System/colors_and_type.css` as a cheat-sheet for ad-hoc HTML; library components apply equivalent styles internally.
-
-- `.h1` — 24/32 medium, primary text
-- `.h2` — 20/28 semibold, primary text
-- `.h3` — 16/24 bold, primary text
-- `.body` — 16/24 regular, secondary text
-- `.label` — 14/20 medium, primary text
-- `.caption` — 12/16 regular, muted text
-- `.nav-label` / `.nav-label--active` — 16/24 Geist
-- `.auth-heading` — 22/28 Inter Tight medium
-
-### 3.6 Tone & voice
-
-When generating copy for screens built with this library:
-
-- **Professional but approachable** — direct, benefit-led. Not overly casual.
-- **Second person ("you")** — e.g. "Welcome back, Sarah."
-- **Action-oriented labels** — "Add Application", "Renew", "Sign out".
-- **Sentence case for body UI**, **Title Case for nav labels**.
-- **No emoji in production UI copy.**
-- **Numbers used sparingly and cleanly** — `7`, `$13,710`, `2`.
-
----
-
-## 4. Spacing & Layout
-
-### 4.1 Spacing scale (4px base)
-
-| Token          | Value | CSS var          |
-| -------------- | ----- | ---------------- |
-| `--space-1`    | 4px   |                  |
-| `--space-2`    | 8px   |                  |
-| `--space-2-5`  | 10px  |                  |
-| `--space-3`    | 12px  |                  |
-| `--space-4`    | 16px  |                  |
-| `--space-5`    | 20px  |                  |
-| `--space-6`    | 24px  |                  |
-| `--space-8`    | 32px  |                  |
-| `--space-10`   | 40px  |                  |
-| `--space-12`   | 48px  |                  |
-| `--space-16`   | 64px  |                  |
-
-Common gaps: **4, 8, 12, 16, 24, 32, 48, 64**.
-
-### 4.2 App layout
-
-| Region           | Size              | Note                                                    |
-| ---------------- | ----------------- | ------------------------------------------------------- |
-| Sidebar width    | **256px** fixed   | `AbSidebar` collapsed state managed via provide/inject  |
-| Topbar height    | **80px**          |                                                         |
-| Content padding  | **24px**          | `--bb-apbd-container-page-padding` (≈ 0.937rem default) |
-| Card padding     | **24–32px**       | `--bb-apbd-card-*` variables                            |
-
-### 4.3 Component sizing scale
-
-Many components expose a `size` prop with values **`xs`, `sm`, `md`, `lg`, `xl`, `xxl`** (default `md`). The size is mapped to per-component padding/font tokens in `_variables.scss` (e.g. `--bb-input-field-padding-md`, `--bb-apbd-btn-padding-md-x`). Pick:
-
-- `xs` / `sm` — dense forms, table inline editors, filter panels
-- `md` — default app content, settings forms, modals
-- `lg` / `xl` — auth screens, wizard steps, marketing surfaces
-- `xxl` — display / hero CTAs
-
----
-
-## 5. Corner Radii
-
-| Token         | Value  | Library variable          | Usage                            |
-| ------------- | ------ | ------------------------- | -------------------------------- |
-| `--radius-xs` | 4px    | —                         | Tags, small pills                |
-| `--radius-sm` | 6px    | `--bb-border-radius-sm`   | Small buttons                    |
-| `--radius-md` | 8px    | `--bb-border-radius`      | Inputs, buttons (sm/md)          |
-| `--radius-lg` | 10px   | `--bb-border-radius-lg`   | Nav items, buttons (lg/xl)       |
-| `--radius-xl` | 12px   | —                         | Search bar, medium cards         |
-| `--radius-2xl`| 14px   | —                         | Icon containers                  |
-| `--radius-3xl`| 16px   | `--bb-apbd-card-border-radius` (≈ 0.875rem) | Cards          |
-| `--radius-pill` | 9999px | —                       | Badges, avatars (`AbAvatar`)     |
-
----
-
-## 6. Shadows & Elevation
-
-Flat by default. Shadows are reserved for cards, dropdowns, popovers, and elevated modals.
-
-| Token            | Value                                                                                | Usage                              |
-| ---------------- | ------------------------------------------------------------------------------------ | ---------------------------------- |
-| `--shadow-xs`    | `0px 1px 2px 0px rgba(16,24,40,0.05)`                                                | Subtle resting elevation           |
-| `--shadow-sm`    | `0px 1px 2px -1px rgba(0,0,0,0.1), 0px 1px 3px 0px rgba(0,0,0,0.1)`                  | Cards (default `AbCard`)           |
-| `--shadow-md`    | `0px 2px 4px -2px rgba(16,24,40,0.06), 0px 4px 8px -2px rgba(16,24,40,0.10)`         | Dropdowns, popovers (`AbPopover`)  |
-| `--shadow-lg`    | `0px 4px 6px -2px rgba(16,24,40,0.03), 0px 12px 16px -4px rgba(16,24,40,0.08)`       | Modals (`AbModal`, `AbEasyModal`)  |
-| `--shadow-card`  | `0px 2px 2px 0px rgba(0,0,0,0.03)`                                                   | Soft card variant                  |
-
-**No gradients on UI surfaces.** Gradients appear only in design documentation headers, never in app chrome.
-
----
-
-## 7. Iconography
-
-**Library: [Lucide Icons](https://lucide.dev/)** — installed as the `lucide-vue-next` peer dependency. Bootstrap Icons is also a peer dep and may be used for a few legacy components.
-
-### Sizing
-
-| Size  | Usage                                       |
-| ----- | ------------------------------------------- |
-| 16×16 | Inline / topbar buttons / dense controls    |
-| 20×20 | Nav items (default), most `AbButton` icons  |
-| 24×24 | Larger nav, prominent actions, empty states |
-
-- **Stroke weight:** 1.5–2px (Lucide default).
-- **Color:** inherits text color; active nav/icons = `--bb-primary` (`#155EEF`); muted = `#717680`.
-
-### Common icons in use
-
-`panel-right-open`, `plus`, `arrow-up`, `arrow-right`, `chevron-left`, `chevron-down`, `sparkles`, `house`, `log-out`, `alert-circle`, `x`, `user`, `refresh-ccw`, `mail`, `search`.
-
-**Rules:** All icons are SVG via Lucide. **No emoji in production UI.** No PNG icons. No custom icon font.
-
----
-
-## 8. Interaction & Motion
-
-### 8.1 Hover / focus / pressed
-
-| State                  | Treatment                                                                  |
-| ---------------------- | -------------------------------------------------------------------------- |
-| Primary button hover   | Darken to Brand/700 `#004EEB` (`--bb-primary-btn-hover`)                   |
-| Nav item hover         | Light blue tint `#EFF4FF` background                                       |
-| Card hover             | Static — no shadow animation by default                                    |
-| Link                   | Brand/600 `#155EEF`; underline on hover                                    |
-| Input focus            | Border `#155EEF`; subtle focus ring `--bb-apbd-input-box-shadow`           |
-| Form check / toggle on | `--bb-apbd-checkbox-checked-form-check-bg` / `--bb-apbd-toggle-checked-bg` |
-
-### 8.2 Motion principles
-
-- **Minimal animation.** No bounces or springs.
-- **Implied CSS ease** (no overrides). Treat `transition: 150–200ms ease` as default.
-- **Sidebar collapse** — toggled via `panel-right-open` icon; uses CSS width transition.
-
----
-
-## 9. Dark mode
-
-Dark mode is opt-in via `[data-bs-theme="dark"]` on the root and managed by the **`useTheme`** composable + **`AbDarkModeToggler`** component (see [AI_REFERENCE.md §4](./AI_REFERENCE.md#4-composables--directives)).
-
-Each theme partial in `playground/skins/themes/_<name>.scss` re-emits brand variables for dark mode. Authors of new components must:
-
-- Use `var(--bb-apbd-bg-color)` and `var(--bb-apbd-border-color)` for surfaces and dividers.
-- Avoid hard-coded `#FFFFFF` / `#EAECF0` etc.
-- Test both light and dark in the playground before shipping.
-
----
-
-## 10. Component → Token Map
-
-How design tokens land in built-in components. Use this when generating layouts so the look stays consistent. For full component APIs, follow each link to [AI_REFERENCE.md](./AI_REFERENCE.md).
-
-| Component                                     | Primary tokens                                                                                          |
-| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| [`AbButton`](./AI_REFERENCE.md#abbutton)      | `--bb-primary`, `--bb-primary-btn-hover`, radii via `--bb-border-radius` / `-lg`, `--bb-apbd-btn-padding-*` |
-| [`AbCard`](./AI_REFERENCE.md#abcard)          | `--bb-apbd-card-border-radius` (`16px`), `--shadow-sm`, surface white, border `#D5D7DA`                 |
-| [`AbModal`](./AI_REFERENCE.md#abmodal) / [`AbEasyModal`](./AI_REFERENCE.md#abeasymodal) | `--bb-apbd-modal-*` paddings, backdrop `rgba(0,0,0,0.7)` (`--bb-apbd-modal-bg-opacity`), `--shadow-lg`  |
-| [`AbInputField`](./AI_REFERENCE.md#abinputfield) / [`AbNumberField`](./AI_REFERENCE.md#abnumberfield) / [`AbMultiSelect`](./AI_REFERENCE.md#abmultiselect) | `--bb-input-field-padding-*`, `--bb-apbd-border-color-focus`, `--bb-apbd-input-box-shadow`              |
-| [`AbBadge`](./AI_REFERENCE.md#abbadge)        | Semantic palette (success / error / warning / info), pill radius `9999px`                               |
-| [`AbAvatar`](./AI_REFERENCE.md#abavatar)      | `--radius-pill`, sizing scale `xs–xxl`                                                                  |
-| [`AbSidebar`](./AI_REFERENCE.md#absidebar) / [`AbSideMenuItem`](./AI_REFERENCE.md#absidemenuitem) | width `256px`, active bg `#EFF4FF`, active text `--bb-primary`, font `--font-nav` (Geist)              |
-| [`AbProgressbar`](./AI_REFERENCE.md#abprogressbar) | `--bb-apbd-progressbar-fill-bg-primary`, semantic color variants                                   |
-| [`AbSlider`](./AI_REFERENCE.md#abslider)      | `--bb-apbd-slider-fill-bg`, `--bb-apbd-slider-thumb-border-color`, `--bb-apbd-slider-thumb-focus-shadow` |
-| [`AbToggle`](./AI_REFERENCE.md#abtoggle) / [`AbFormCheck`](./AI_REFERENCE.md#abformcheck--abradioinput) | `--bb-apbd-toggle-checked-bg`, `--bb-apbd-checkbox-checked-form-check-bg`                           |
-| [`AbToast`](./AI_REFERENCE.md#abtoast) (via `useToast`) | Semantic palette, `--shadow-md`                                                              |
-| [`AbTable`](./AI_REFERENCE.md#abtable)        | Header bg `#F9FAFB`, divider `--bb-apbd-border-color`                                                   |
-| [`AbDarkModeToggler`](./AI_REFERENCE.md#abdarkmodetoggler) | Pairs with `useTheme`; flips `[data-bs-theme]` on root                                       |
-
----
-
-## 11. Implementation Notes
-
-### 11.1 SCSS structure
-
-```
-src/styles/
-├── index.scss            # Main entry; wraps imports in .#{$app_class}
-├── _prefix.scss          # $prefix: "bb-"  /  $app_class: "appsbd-app"
-├── _variables.scss       # All --bb-apbd-* design tokens
-├── _mixins.scss
-├── components/           # Per-component partials (do NOT wrap in .#{$app_class})
-│   ├── _button.scss
-│   ├── _card.scss
-│   └── ...
-└── rtl/                  # RTL-specific overrides
-```
-
-When editing any `.scss` under `src/styles/`, invoke the **`scss-conventions`** project skill — it encodes the prefix-vs-class rule, the no-double-nesting rule for component partials, and the dark-mode tokens.
-
-### 11.2 Adding a new design token
-
-1. Decide whether Bootstrap already has a variable for it. If yes, override there.
-2. Otherwise, add it to `src/styles/_variables.scss` under the `apbd-` namespace: `--#{$prefix}apbd-<component>-<property>`.
-3. Use the new token in component partials via `var(--#{$prefix}apbd-...)`.
-4. If the token participates in theming, add a corresponding line to each `playground/skins/themes/_<color>.scss` partial.
-
-### 11.3 Adding a new color skin
-
-Use the **`add-theme-skin`** project skill — it wires the 5 places a new skin must touch:
-
-1. `playground/skins/themes/_<name>.scss` (defines `$theme-color`, `$theme-color-light`, `$theme-color-dark`, `$theme-color-hover`, `$border-color-focus-light`)
-2. `playground/skins/<name>.scss` (skin wrapper)
-3. `vite.config.js` rollup input + `assetFileNames` allow-list
-4. `AbColorPicker` option in the playground
-5. `toggleTheme` name → CSS mapping
-
-### 11.4 Adding a new component
-
-Use the **`add-ab-component`** project skill — it walks the 9-step wiring (SFC + barrel export, SCSS partial + correct import location, playground docs page, router entry, sidebar menu item, `ComponentsOverview` entry, AI reference files).
-
-### 11.5 Updating tokens or component APIs
-
-Whenever a component's public API or visual tokens change, update **all four** of:
-
-1. The component's playground `*Test.vue` (use the **`write-component-docs`** skill).
-2. [AI_REFERENCE.md](./AI_REFERENCE.md) (component table row + section-3 API block).
-3. `.ai/ai_ref_<ComponentName>.md`.
-4. This file (**`design-system.md`**) if the change adds/renames a public design token.
-
-The **`update-ai-reference`** project skill enforces (2) and (3).
-
----
-
-## 12. Source materials
-
-- **`Appsbd Design System/README.md`** — design system narrative (foundations, tone, iconography).
-- **`Appsbd Design System/colors_and_type.css`** — CSS-variable form of every token below; copy-paste-ready.
-- **`Appsbd Design System/preview/*.html`** — visual specimens for colors, type, spacing, shadows, buttons, badges, inputs, nav, cards, avatars, tabs.
-- **`Appsbd Design System/ui_kits/system-admin/`** — interactive prototype (Dashboard, Tickets, Auth) that exercises every token in context.
-- **`AI_REFERENCE.md`** — component API reference; the "what props/events/slots" companion to this "what colors/sizes/spacings" document.
+# Appsbd UI Library — Design System
+
+**AI Assistant Instructions**:
+This document is the **visual-language counterpart** to [AI_REFERENCE.md](./AI_REFERENCE.md). Where `AI_REFERENCE.md` documents component **APIs** (props, events, slots), this file documents the **design tokens** (colors, typography, spacing, radii, shadows, motion) that those components are built on. Use this file when you need to:
+
+- Pick the right color, font size, radius, or spacing for new UI
+- Style custom layouts that should feel consistent with built-in `Ab*` components
+- Theme the library (light/dark, brand re-skinning)
+- Translate a Figma mock from the Appsbd Design System to library code
+
+**Source of truth.** The visual foundations below are derived from the **Appsbd Design System** folder (`./Appsbd Design System/`) — itself extracted from the **"Kigen design system"** Figma file. The library implements these tokens in SCSS using the `bb-` CSS-variable prefix and the `.apbd-` class prefix. Where a design-system token has a direct library variable, both names are listed.
+
+---
+
+## 1. Design Philosophy
+
+The library follows four rules, in priority order:
+
+1. **Bootstrap variables first.** If a need can be met by overriding a Bootstrap CSS variable (e.g. `--bb-primary`, `--bb-border-radius`), do that.
+2. **Custom tokens second.** When Bootstrap has no matching variable (skeletons, sliders, custom panels), define a new token in `src/styles/_variables.scss` using the **`apbd-`** namespace under the **`bb-`** prefix, e.g. `--bb-apbd-bg-color`.
+3. **Class-variant over new component.** Layout variations of an existing base component (e.g. `tile-card`, `item-card`, `insight-card` for `AbCard`) are **CSS class extensions** in the corresponding `_component.scss`, not new SFCs.
+4. **Dark-mode safe colors.** Use `var(--bb-apbd-bg-color)` and `var(--bb-apbd-border-color)` inside component styles instead of `body-bg` or `border-color`, so light/dark switching just works.
+
+> **Prefix rule.** CSS **class names** use `.apbd-` (e.g. `.apbd-skeleton`). CSS **variables** use `#{$prefix}` interpolation (e.g. `var(--#{$prefix}apbd-border-color)`, which compiles to `var(--bb-apbd-border-color)`).
+
+---
+
+## 2. Brand & Color System
+
+### 2.1 Primary brand color
+
+The library's primary brand color is **Brand/600 — `#155EEF`** (Appsbd blue). It is the value of `--bb-primary` in the default (`blue`) skin and drives the focus ring, primary buttons, active nav, links, and component accents.
+
+### 2.2 Brand blue scale
+
+Used for primary actions, links, focus rings, active states.
+
+| Token       | Hex       | Library variable          | Usage                          |
+| ----------- | --------- | ------------------------- | ------------------------------ |
+| Brand/25    | `#F5F8FF` | —                         | Very light tint                |
+| Brand/50    | `#EFF4FF` | `--bb-primary-light`      | Active nav bg, light highlight |
+| Brand/100   | `#D1E0FF` | —                         | Hover tint                     |
+| Brand/200   | `#B2CCFF` | —                         | Border on blue tint            |
+| Brand/300   | `#84ADFF` | `--bb-apbd-border-color-focus` | Focus ring (light)        |
+| Brand/400   | `#528BFF` | —                         | Secondary interactive          |
+| Brand/500   | `#2970FF` | (dark-mode `--bb-primary`) | Hover on primary              |
+| **Brand/600** | **`#155EEF`** | **`--bb-primary` (light)** | **Primary action, brand blue** |
+| Brand/700   | `#004EEB` | `--bb-primary-btn-hover`  | Pressed / hover-darkened       |
+| Brand/800   | `#0040C1` | —                         | Dark brand                     |
+| Brand/900   | `#00359E` | —                         | Very dark                      |
+| Brand/950   | `#002266` | —                         | Darkest                        |
+
+### 2.3 Neutral / gray scale
+
+Used for text, borders, surfaces, and dividers.
+
+| Token    | Hex       | Usage                          |
+| -------- | --------- | ------------------------------ |
+| Gray/25  | `#FCFCFD` | Subtle backgrounds             |
+| Gray/50  | `#F9FAFB` | Table headers, inputs          |
+| Gray/100 | `#F2F4F7` | Light backgrounds, subtle border |
+| Gray/200 | `#EAECF0` | Default dividers               |
+| Gray/300 | `#D0D5DD` | Borders                        |
+| Gray/400 | `#98A2B3` | Disabled, placeholder          |
+| Gray/500 | `#667085` | Muted text                     |
+| Gray/600 | `#475569` | Secondary text                 |
+| Gray/700 | `#344054` | Body text                      |
+| Gray/800 | `#1D2939` | Heading text                   |
+| Gray/900 | `#101828` | Primary text                   |
+
+### 2.4 Semantic colors
+
+Used by `AbBaseAlert`, `AbBadge`, `AbToast`, `AbButton variant`, form error states.
+
+| Role        | Background | Border    | Text/Icon | Solid     |
+| ----------- | ---------- | --------- | --------- | --------- |
+| **Success** | `#ECFDF3`  | `#ABEFC6` | `#085D3A` | `#00C950` |
+| **Error**   | `#FEF2F2`  | `#FECACA` | `#B91C1C` | `#FB2C36` |
+| **Warning** | `#FFFBEB`  | `#FDE68A` | `#92400E` | `#EEB004` |
+| **Info**    | `#EFF4FF`  | `#B2CCFF` | `#155EEF` | `#2970FF` |
+
+These map to Bootstrap's `--bb-success`, `--bb-danger`, `--bb-warning`, `--bb-info` variants used by `AbButton`'s `variant` prop and `AbBadge`'s `variant` prop.
+
+### 2.5 Surface & layout colors
+
+| Role               | Hex       | Library variable               |
+| ------------------ | --------- | ------------------------------ |
+| App shell bg       | `#EBEFF5` | (page wrapper)                 |
+| Card / panel       | `#FFFFFF` | `--bb-apbd-bg-color` (light)   |
+| Sidebar bg         | `#FFFFFF` | (`AbSidebar` root)             |
+| Topbar bg          | `#FFFFFF` |                                |
+| Table header bg    | `#F9FAFB` | (`AbTable` thead)              |
+| Input bg           | `#FFFFFF` |                                |
+| Active nav-item bg | `#EFF4FF` | `--bb-apbd-sidebar-item-active-bg` |
+
+> **Dark-mode rule.** Component styles must read from `var(--bb-apbd-bg-color)` / `var(--bb-apbd-border-color)` instead of hard-coding `#FFFFFF` / `#EAECF0`, so the values flip cleanly when `[data-bs-theme="dark"]` is set on the root.
+
+### 2.6 Borders
+
+| Role           | Hex       | Library variable               |
+| -------------- | --------- | ------------------------------ |
+| Default        | `#EAECF0` | `--bb-apbd-border-color`       |
+| Strong         | `#D5D7DA` | `--bb-apbd-border-color-strong` |
+| Subtle         | `#F2F4F7` | —                              |
+| Brand / focus  | `#155EEF` | `--bb-primary`                 |
+| Focus ring     | `#84ADFF` | `--bb-apbd-border-color-focus` |
+| Error          | `#FDA29B` | `--bb-apbd-input-error-border` |
+
+### 2.7 Theme skins
+
+The library ships **multiple color skins** under `playground/skins/themes/`. Each is a `_<name>.scss` partial defining `$theme-color`, `$theme-color-light`, `$theme-color-dark`, `$theme-color-hover`, and `$border-color-focus-light`, then re-emitting them as `--bb-primary`, `--bb-primary-light`, `--bb-primary-rgb`, etc.
+
+**Built-in skins:** `blue` (default), `black`, `cyan`, `gray`, `green`, `orange`, `pink`, `purple`, `red`, `violet`.
+
+Skin switching is wired through the `AbColorPicker` in the playground; use the **`add-theme-skin`** project skill to add a new skin so all five wiring steps (theme partial, skin wrapper, vite rollup entry, picker option, `toggleTheme` mapping) are applied consistently.
+
+---
+
+## 3. Typography
+
+### 3.1 Font families
+
+| Role            | Family           | Library token (CSS) | Usage                                    |
+| --------------- | ---------------- | ------------------- | ---------------------------------------- |
+| **Sans (UI)**   | **Inter**        | `--font-sans`       | All body, labels, headings, form fields  |
+| Nav             | Geist            | `--font-nav`        | Sidebar nav items, app brand name        |
+| Display         | Inter            | `--font-display`    | Hero / marketing display text            |
+| Auth headings   | Inter Tight      | `--font-auth`       | Login / register screen titles           |
+| Mono            | Geist            | `--font-mono`       | `<code>`, mono helpers                   |
+
+`Inter` is the variable font shipped in `Appsbd Design System/fonts/`. `Geist` and `Inter Tight` come from Google Fonts.
+
+### 3.2 Display scale
+
+For marketing pages, dashboards' hero numbers, and landing screens.
+
+| Style          | Size | Weight | Line height | Token                          |
+| -------------- | ---- | ------ | ----------- | ------------------------------ |
+| Display 2xl    | 72px | 700    | 1.0         | `--text-display-2xl-*`         |
+| Display xl     | 60px | 600    | 1.1         | `--text-display-xl-*`          |
+| Display lg     | 48px | 600    | 1.1         | `--text-display-lg-*`          |
+| Display md     | 44px | 600    | 1.15        | `--text-display-md-*`          |
+| Display sm     | 30px | 600    | 1.2         | `--text-display-sm-*`          |
+| Display xs     | 24px | 600    | 1.2         | `--text-display-xs-*`          |
+
+### 3.3 Text scale
+
+For app body, labels, captions.
+
+| Style    | Size | Weight | Line height | Library variable                     | Usage                  |
+| -------- | ---- | ------ | ----------- | ------------------------------------ | ---------------------- |
+| Text xl  | 20px | 400    | 30px        | `--bb-apbd-fs-lg` (1.5rem)           | Large body, subheaders |
+| Text lg  | 18px | 400    | 28px        | —                                    | Subheadings            |
+| Text md  | 16px | 400    | 24px        | `--bb-apbd-fs-md` (1rem)             | Body text (default)    |
+| Text sm  | 14px | 400    | 20px        | `--bb-apbd-fs-sm` (0.875rem)         | Labels, nav, hints     |
+| Text xs  | 12px | 400    | 16px        | `--bb-apbd-fs-xs` (0.75rem)          | Captions, meta         |
+| Text xxs | 11px | 400    | 14px        | —                                    | Micro labels           |
+
+### 3.4 Font weights
+
+| Token  | Weight | Library variable              |
+| ------ | ------ | ----------------------------- |
+| Thin   | 300    | `--bb-apbd-fw-thin`           |
+| Normal | 400    | `--bb-apbd-fw-normal`         |
+| Bold   | 500    | `--bb-apbd-fw-bold` (medium)  |
+| Bolder | 600    | `--bb-apbd-fw-bolder` (semi)  |
+| Boldest| 700    | `--bb-apbd-fw-boldest`        |
+
+### 3.5 Semantic type helpers
+
+These class names exist in `Appsbd Design System/colors_and_type.css` as a cheat-sheet for ad-hoc HTML; library components apply equivalent styles internally.
+
+- `.h1` — 24/32 medium, primary text
+- `.h2` — 20/28 semibold, primary text
+- `.h3` — 16/24 bold, primary text
+- `.body` — 16/24 regular, secondary text
+- `.label` — 14/20 medium, primary text
+- `.caption` — 12/16 regular, muted text
+- `.nav-label` / `.nav-label--active` — 16/24 Geist
+- `.auth-heading` — 22/28 Inter Tight medium
+
+### 3.6 Tone & voice
+
+When generating copy for screens built with this library:
+
+- **Professional but approachable** — direct, benefit-led. Not overly casual.
+- **Second person ("you")** — e.g. "Welcome back, Sarah."
+- **Action-oriented labels** — "Add Application", "Renew", "Sign out".
+- **Sentence case for body UI**, **Title Case for nav labels**.
+- **No emoji in production UI copy.**
+- **Numbers used sparingly and cleanly** — `7`, `$13,710`, `2`.
+
+---
+
+## 4. Spacing & Layout
+
+### 4.1 Spacing scale (4px base)
+
+| Token          | Value | CSS var          |
+| -------------- | ----- | ---------------- |
+| `--space-1`    | 4px   |                  |
+| `--space-2`    | 8px   |                  |
+| `--space-2-5`  | 10px  |                  |
+| `--space-3`    | 12px  |                  |
+| `--space-4`    | 16px  |                  |
+| `--space-5`    | 20px  |                  |
+| `--space-6`    | 24px  |                  |
+| `--space-8`    | 32px  |                  |
+| `--space-10`   | 40px  |                  |
+| `--space-12`   | 48px  |                  |
+| `--space-16`   | 64px  |                  |
+
+Common gaps: **4, 8, 12, 16, 24, 32, 48, 64**.
+
+### 4.2 App layout
+
+| Region           | Size              | Note                                                    |
+| ---------------- | ----------------- | ------------------------------------------------------- |
+| Sidebar width    | **256px** fixed   | `AbSidebar` collapsed state managed via provide/inject  |
+| Topbar height    | **80px**          |                                                         |
+| Content padding  | **24px**          | `--bb-apbd-container-page-padding` (≈ 0.937rem default) |
+| Card padding     | **24–32px**       | `--bb-apbd-card-*` variables                            |
+
+### 4.3 Component sizing scale
+
+Many components expose a `size` prop with values **`xs`, `sm`, `md`, `lg`, `xl`, `xxl`** (default `md`). The size is mapped to per-component padding/font tokens in `_variables.scss` (e.g. `--bb-input-field-padding-md`, `--bb-apbd-btn-padding-md-x`). Pick:
+
+- `xs` / `sm` — dense forms, table inline editors, filter panels
+- `md` — default app content, settings forms, modals
+- `lg` / `xl` — auth screens, wizard steps, marketing surfaces
+- `xxl` — display / hero CTAs
+
+---
+
+## 5. Corner Radii
+
+| Token         | Value  | Library variable          | Usage                            |
+| ------------- | ------ | ------------------------- | -------------------------------- |
+| `--radius-xs` | 4px    | —                         | Tags, small pills                |
+| `--radius-sm` | 6px    | `--bb-border-radius-sm`   | Small buttons                    |
+| `--radius-md` | 8px    | `--bb-border-radius`      | Inputs, buttons (sm/md)          |
+| `--radius-lg` | 10px   | `--bb-border-radius-lg`   | Nav items, buttons (lg/xl)       |
+| `--radius-xl` | 12px   | —                         | Search bar, medium cards         |
+| `--radius-2xl`| 14px   | —                         | Icon containers                  |
+| `--radius-3xl`| 16px   | `--bb-apbd-card-border-radius` (≈ 0.875rem) | Cards          |
+| `--radius-pill` | 9999px | —                       | Badges, avatars (`AbAvatar`)     |
+
+---
+
+## 6. Shadows & Elevation
+
+Flat by default. Shadows are reserved for cards, dropdowns, popovers, and elevated modals.
+
+| Token            | Value                                                                                | Usage                              |
+| ---------------- | ------------------------------------------------------------------------------------ | ---------------------------------- |
+| `--shadow-xs`    | `0px 1px 2px 0px rgba(16,24,40,0.05)`                                                | Subtle resting elevation           |
+| `--shadow-sm`    | `0px 1px 2px -1px rgba(0,0,0,0.1), 0px 1px 3px 0px rgba(0,0,0,0.1)`                  | Cards (default `AbCard`)           |
+| `--shadow-md`    | `0px 2px 4px -2px rgba(16,24,40,0.06), 0px 4px 8px -2px rgba(16,24,40,0.10)`         | Dropdowns, popovers (`AbPopover`)  |
+| `--shadow-lg`    | `0px 4px 6px -2px rgba(16,24,40,0.03), 0px 12px 16px -4px rgba(16,24,40,0.08)`       | Modals (`AbModal`, `AbEasyModal`)  |
+| `--shadow-card`  | `0px 2px 2px 0px rgba(0,0,0,0.03)`                                                   | Soft card variant                  |
+
+**No gradients on UI surfaces.** Gradients appear only in design documentation headers, never in app chrome.
+
+---
+
+## 7. Iconography
+
+**Library: [Lucide Icons](https://lucide.dev/)** — installed as the `lucide-vue-next` peer dependency. Bootstrap Icons is also a peer dep and may be used for a few legacy components.
+
+### Sizing
+
+| Size  | Usage                                       |
+| ----- | ------------------------------------------- |
+| 16×16 | Inline / topbar buttons / dense controls    |
+| 20×20 | Nav items (default), most `AbButton` icons  |
+| 24×24 | Larger nav, prominent actions, empty states |
+
+- **Stroke weight:** 1.5–2px (Lucide default).
+- **Color:** inherits text color; active nav/icons = `--bb-primary` (`#155EEF`); muted = `#717680`.
+
+### Common icons in use
+
+`panel-right-open`, `plus`, `arrow-up`, `arrow-right`, `chevron-left`, `chevron-down`, `sparkles`, `house`, `log-out`, `alert-circle`, `x`, `user`, `refresh-ccw`, `mail`, `search`.
+
+**Rules:** All icons are SVG via Lucide. **No emoji in production UI.** No PNG icons. No custom icon font.
+
+---
+
+## 8. Interaction & Motion
+
+### 8.1 Hover / focus / pressed
+
+| State                  | Treatment                                                                  |
+| ---------------------- | -------------------------------------------------------------------------- |
+| Primary button hover   | Darken to Brand/700 `#004EEB` (`--bb-primary-btn-hover`)                   |
+| Nav item hover         | Light blue tint `#EFF4FF` background                                       |
+| Card hover             | Static — no shadow animation by default                                    |
+| Link                   | Brand/600 `#155EEF`; underline on hover                                    |
+| Input focus            | Border `#155EEF`; subtle focus ring `--bb-apbd-input-box-shadow`           |
+| Form check / toggle on | `--bb-apbd-checkbox-checked-form-check-bg` / `--bb-apbd-toggle-checked-bg` |
+
+### 8.2 Motion principles
+
+- **Minimal animation.** No bounces or springs.
+- **Implied CSS ease** (no overrides). Treat `transition: 150–200ms ease` as default.
+- **Sidebar collapse** — toggled via `panel-right-open` icon; uses CSS width transition.
+
+---
+
+## 9. Dark mode
+
+Dark mode is opt-in via `[data-bs-theme="dark"]` on the root and managed by the **`useTheme`** composable + **`AbDarkModeToggler`** component (see [AI_REFERENCE.md §4](./AI_REFERENCE.md#4-composables--directives)).
+
+Each theme partial in `playground/skins/themes/_<name>.scss` re-emits brand variables for dark mode. Authors of new components must:
+
+- Use `var(--bb-apbd-bg-color)` and `var(--bb-apbd-border-color)` for surfaces and dividers.
+- Avoid hard-coded `#FFFFFF` / `#EAECF0` etc.
+- Test both light and dark in the playground before shipping.
+
+---
+
+## 10. Component → Token Map
+
+How design tokens land in built-in components. Use this when generating layouts so the look stays consistent. For full component APIs, follow each link to [AI_REFERENCE.md](./AI_REFERENCE.md).
+
+| Component                                     | Primary tokens                                                                                          |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| [`AbButton`](./AI_REFERENCE.md#abbutton)      | `--bb-primary`, `--bb-primary-btn-hover`, radii via `--bb-border-radius` / `-lg`, `--bb-apbd-btn-padding-*` |
+| [`AbCard`](./AI_REFERENCE.md#abcard)          | `--bb-apbd-card-border-radius` (`16px`), `--shadow-sm`, surface white, border `#D5D7DA`                 |
+| [`AbModal`](./AI_REFERENCE.md#abmodal) / [`AbEasyModal`](./AI_REFERENCE.md#abeasymodal) | `--bb-apbd-modal-*` paddings, backdrop `rgba(0,0,0,0.7)` (`--bb-apbd-modal-bg-opacity`), `--shadow-lg`  |
+| [`AbInputField`](./AI_REFERENCE.md#abinputfield) / [`AbNumberField`](./AI_REFERENCE.md#abnumberfield) / [`AbMultiSelect`](./AI_REFERENCE.md#abmultiselect) | `--bb-input-field-padding-*`, `--bb-apbd-border-color-focus`, `--bb-apbd-input-box-shadow`              |
+| [`AbBadge`](./AI_REFERENCE.md#abbadge)        | Semantic palette (success / error / warning / info), pill radius `9999px`                               |
+| [`AbAvatar`](./AI_REFERENCE.md#abavatar)      | `--radius-pill`, sizing scale `xs–xxl`                                                                  |
+| [`AbSidebar`](./AI_REFERENCE.md#absidebar) / [`AbSideMenuItem`](./AI_REFERENCE.md#absidemenuitem) | width `256px`, active bg `#EFF4FF`, active text `--bb-primary`, font `--font-nav` (Geist)              |
+| [`AbProgressbar`](./AI_REFERENCE.md#abprogressbar) | `--bb-apbd-progressbar-fill-bg-primary`, semantic color variants                                   |
+| [`AbSlider`](./AI_REFERENCE.md#abslider)      | `--bb-apbd-slider-fill-bg`, `--bb-apbd-slider-thumb-border-color`, `--bb-apbd-slider-thumb-focus-shadow` |
+| [`AbToggle`](./AI_REFERENCE.md#abtoggle) / [`AbFormCheck`](./AI_REFERENCE.md#abformcheck--abradioinput) | `--bb-apbd-toggle-checked-bg`, `--bb-apbd-checkbox-checked-form-check-bg`                           |
+| [`AbToast`](./AI_REFERENCE.md#abtoast) (via `useToast`) | Semantic palette, `--shadow-md`                                                              |
+| [`AbTable`](./AI_REFERENCE.md#abtable)        | Header bg `#F9FAFB`, divider `--bb-apbd-border-color`                                                   |
+| [`AbDarkModeToggler`](./AI_REFERENCE.md#abdarkmodetoggler) | Pairs with `useTheme`; flips `[data-bs-theme]` on root                                       |
+
+---
+
+## 11. Implementation Notes
+
+### 11.1 SCSS structure
+
+```
+src/styles/
+├── index.scss            # Main entry; wraps imports in .#{$app_class}
+├── _prefix.scss          # $prefix: "bb-"  /  $app_class: "appsbd-app"
+├── _variables.scss       # All --bb-apbd-* design tokens
+├── _mixins.scss
+├── components/           # Per-component partials (do NOT wrap in .#{$app_class})
+│   ├── _button.scss
+│   ├── _card.scss
+│   └── ...
+└── rtl/                  # RTL-specific overrides
+```
+
+When editing any `.scss` under `src/styles/`, invoke the **`scss-conventions`** project skill — it encodes the prefix-vs-class rule, the no-double-nesting rule for component partials, and the dark-mode tokens.
+
+### 11.2 Adding a new design token
+
+1. Decide whether Bootstrap already has a variable for it. If yes, override there.
+2. Otherwise, add it to `src/styles/_variables.scss` under the `apbd-` namespace: `--#{$prefix}apbd-<component>-<property>`.
+3. Use the new token in component partials via `var(--#{$prefix}apbd-...)`.
+4. If the token participates in theming, add a corresponding line to each `playground/skins/themes/_<color>.scss` partial.
+
+### 11.3 Adding a new color skin
+
+Use the **`add-theme-skin`** project skill — it wires the 5 places a new skin must touch:
+
+1. `playground/skins/themes/_<name>.scss` (defines `$theme-color`, `$theme-color-light`, `$theme-color-dark`, `$theme-color-hover`, `$border-color-focus-light`)
+2. `playground/skins/<name>.scss` (skin wrapper)
+3. `vite.config.js` rollup input + `assetFileNames` allow-list
+4. `AbColorPicker` option in the playground
+5. `toggleTheme` name → CSS mapping
+
+### 11.4 Adding a new component
+
+Use the **`add-ab-component`** project skill — it walks the 9-step wiring (SFC + barrel export, SCSS partial + correct import location, playground docs page, router entry, sidebar menu item, `ComponentsOverview` entry, AI reference files).
+
+### 11.5 Updating tokens or component APIs
+
+Whenever a component's public API or visual tokens change, update **all four** of:
+
+1. The component's playground `*Test.vue` (use the **`write-component-docs`** skill).
+2. [AI_REFERENCE.md](./AI_REFERENCE.md) (component table row + section-3 API block).
+3. `.ai/ai_ref_<ComponentName>.md`.
+4. This file (**`design-system.md`**) if the change adds/renames a public design token.
+
+The **`update-ai-reference`** project skill enforces (2) and (3).
+
+---
+
+## 12. Source materials
+
+- **`Appsbd Design System/README.md`** — design system narrative (foundations, tone, iconography).
+- **`Appsbd Design System/colors_and_type.css`** — CSS-variable form of every token below; copy-paste-ready.
+- **`Appsbd Design System/preview/*.html`** — visual specimens for colors, type, spacing, shadows, buttons, badges, inputs, nav, cards, avatars, tabs.
+- **`Appsbd Design System/ui_kits/system-admin/`** — interactive prototype (Dashboard, Tickets, Auth) that exercises every token in context.
+- **`AI_REFERENCE.md`** — component API reference; the "what props/events/slots" companion to this "what colors/sizes/spacings" document.