docs(design): align token contract and skill

.agents/skills/kilo-design/AGENTS.md

@@ -0,0 +1,27 @@
+# Kilo Design Skill Maintenance
+
+## Purpose
+
+Keep frontend design work aligned with root `DESIGN.md` while translating its contract into practical web, mobile, Storybook, accessibility, responsive, interaction, motion, and UX-writing guidance.
+
+## How the skill works
+
+1. `SKILL.md` loads root `DESIGN.md` first.
+2. `reference/kilo-brand.md` maps the contract to repository implementation.
+3. Concern-specific references add focused guidance without redefining tokens.
+4. Existing CSS and components are implementation evidence, not higher-priority sources. Differences from `DESIGN.md` are drift.
+
+## Validation
+
+After changing this skill:
+
+- Search all skill Markdown for retired token values and stale implementation claims.
+- Check compact Markdown table padding with `bun run script/check-md-table-padding.ts`.
+- Run `git diff --check` for changed skill files.
+
+## Change guidelines
+
+- Update root `DESIGN.md` before changing canonical token names, values, domain mappings, typography metrics, radius, or spacing.
+- Keep exact token values in `DESIGN.md`; references should link roles to implementation and avoid duplicating the full contract.
+- Preserve Kilo-specific defaults: dark-first product UI, one primary CTA per surface, six-role surface ladder, fixed status domains, Inter/Roboto Mono roles, compact rhythm, Radix/shadcn primitives, restrained motion, and direct UX copy.
+- When implementation migrates, remove stale warnings immediately. Do not preserve resolved issues as historical guidance.

.agents/skills/kilo-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kilo-design
-description: Use when designing, reviewing, polishing, adapting, or implementing Kilo Code frontend UI. Applies Kilo brand rules, shadcn/Radix component conventions, OKLCH tokens, Inter/Roboto Mono/JetBrains Mono typography, compact product rhythm, restrained motion, and Kilo voice guidelines. Triggers on web app screens (apps/web), Storybook components, React Native mobile surfaces (apps/mobile), marketing/landing pages, onboarding, empty states, forms, dialogs, dashboards, billing, sidebar, theming, accessibility, and visual QA. Triggers on terms like "design", "redesign", "polish", "critique", "audit", "typeset", "typography", "fonts", "color", "palette", "brand", "spacing", "layout", "grid", "motion", "animate", "transitions", "interaction", "forms", "focus", "responsive", "mobile", "breakpoints", "UX copy", "microcopy", "error states", "empty states", "on-brand", "Kilo voice". Not for backend-only work.
+description: Use when designing, reviewing, polishing, adapting, or implementing Kilo Code frontend UI. Applies the DESIGN.md token contract, Kilo brand rules, shadcn/Radix component conventions, exact color tokens, Inter/Roboto Mono/JetBrains Mono typography, compact product rhythm, restrained motion, and Kilo voice guidelines. Triggers on web app screens (apps/web), Storybook components, React Native mobile surfaces (apps/mobile), marketing/landing pages, onboarding, empty states, forms, dialogs, dashboards, billing, sidebar, theming, accessibility, and visual QA. Triggers on terms like "design", "redesign", "polish", "critique", "audit", "typeset", "typography", "fonts", "color", "palette", "brand", "spacing", "layout", "grid", "motion", "animate", "transitions", "interaction", "forms", "focus", "responsive", "mobile", "breakpoints", "UX copy", "microcopy", "error states", "empty states", "on-brand", "Kilo voice". Not for backend-only work.
 license: Apache 2.0 derivative of pbakaus/impeccable, adapted for Kilo Code. See NOTICE.md.
 ---
 
@@ -10,21 +10,16 @@ Design guidance for the Kilo Code frontend. Use this skill whenever the
 task involves how something looks, how it behaves, how it reads, or how
 it adapts.
 
-## Canonical rule: Kilo brand first
+## Canonical rule: design contract first
 
-The overlay in `reference/kilo-brand.md` is the source of truth. When any
-other reference in this skill conflicts with `kilo-brand.md`,
-`kilo-brand.md` wins.
+Root `DESIGN.md` is the source of truth for token names, exact values, domain mappings, typography roles, radius, and spacing. `reference/kilo-brand.md` explains how to apply that contract. When guidance, existing CSS, or a component conflicts with `DESIGN.md`, treat it as implementation drift rather than precedent.
 
-Load `reference/kilo-brand.md` on every invocation of this skill before
-picking tokens, typography, layout, or motion. It captures:
+Load `DESIGN.md` and `reference/kilo-brand.md` on every invocation before picking tokens, typography, layout, or motion. Together they define:
 
-- Kilo's dark-first web theme, mobile light/dark token split, and existing
-  CSS tokens.
-- Brand yellow-green `primary` token as the primary CTA color, used once
-  per surface.
-- Typography (Inter / Roboto Mono / JetBrains Mono) and the known
-  font-token mismatch.
+- Kilo's dark-first web theme and six-role surface ladder.
+- Brand yellow-green `primary` token as the primary CTA color, used once per surface.
+- Fixed status-domain mappings, syntax colors, and diff colors.
+- Inter / Roboto Mono typography roles and editor-only JetBrains Mono usage.
 - Spacing, radius, component, and motion conventions.
 - Kilo-specific anti-patterns to reject on sight.
 
@@ -45,7 +40,7 @@ When unclear, treat the surface as Product UI.
 
 Given a user prompt that invokes this skill:
 
-1. Always load `reference/kilo-brand.md`.
+1. Always load root `DESIGN.md`, then `reference/kilo-brand.md`.
 2. Identify the dominant concern from the prompt and load the matching
    reference(s):
 
@@ -73,12 +68,8 @@ Given a user prompt that invokes this skill:
 
 Follow these on every task:
 
-1. **Inspect before editing.** Open `apps/web/src/app/globals.css`, the
-   relevant component under `apps/web/src/components/`, and any
-   Storybook story before proposing visual changes.
-2. **Prefer existing tokens, utilities, and components.** Before adding
-   a new color, font, radius, or primitive, confirm no existing one
-   solves the problem.
+1. **Inspect before editing.** Open root `DESIGN.md`, `apps/web/src/app/globals.css`, the relevant component under `apps/web/src/components/`, and any Storybook story before proposing visual changes.
+2. **Prefer compliant tokens, utilities, and components.** Reuse existing implementation only when it maps to `DESIGN.md`. If it differs, report or fix the drift instead of copying it.
 3. **Do not rename or restructure the shadcn UI layer** unless the user
    explicitly asks for a design-system refactor.
 4. **Use the `primary` token for primary CTAs.** The product primary is the
@@ -94,24 +85,19 @@ Follow these on every task:
    tablet/laptop (~768–1024px), wide desktop (~1440px+).
 9. **Use Kilo voice** (see `reference/ux-writing.md`) for any copy you
    add or rewrite.
-10. **Surface conflicts.** If the user's ask conflicts with
-    `kilo-brand.md`, raise the conflict and propose a path forward
-    before silently overriding the brand system.
+10. **Surface conflicts.** If the user's ask conflicts with `DESIGN.md`, raise the conflict and propose a path forward before silently overriding the design contract.
 
 ## Implementing code changes
 
 When producing code:
 
-- Use Tailwind utilities that map to semantic tokens
-  (`bg-background`, `text-foreground`, `border-border`, `bg-primary`,
-  `text-primary-foreground`, etc.) before reaching for hex.
+- Use Tailwind utilities that map to semantic tokens before hex: `bg-background`, `text-foreground`, `border-border`, `bg-primary`, and `text-primary-foreground` for broad semantics; `bg-surface-inset`, `bg-surface-raised`, `bg-surface-overlay`, `bg-surface-hover`, and `bg-surface-selected` for exact surface roles; syntax, diff, and status utilities for those domains.
 - Extend `cva` variants in existing `ui/` primitives rather than cloning.
-- Icons: `lucide-react`, typically `size-4`, inheriting `currentColor`.
+- Icons: `lucide-react`, typically `size-4`, inheriting `currentColor`; use `size-icon-sm` for canonical 14px compact/status icons.
 - Add `aria-label` to icon-only buttons.
 - Use Radix + shadcn wrappers for overlays (dialog, dropdown, popover,
   tooltip, sheet) — do not hand-roll positioning.
-- Match compact rhythm: `h-8` / `h-9` / `h-10` controls, `h-14` topbar,
-  `p-6` cards.
+- Match compact rhythm: `h-8` / `h-control-default` / `h-10` controls, `h-14` topbar, and `p-6` cards. Use `h-control-touch` or `size-control-touch` where touch targets need 44px.
 - Prefer `gap-*` over ad-hoc margins.
 
 ## Running a design review
@@ -148,18 +134,17 @@ This skill is intentionally scoped. It does **not**:
 
 - Run automated anti-pattern scans.
 - Run or expose Impeccable's "live mode."
-- Generate a root `DESIGN.md`.
-- Rewrite the font-token mismatch or migrate every legacy hardcoded blue
-  CTA. Those are real follow-ups but belong in separate,
-  design-system-scoped PRs.
+- Generate or redefine root `DESIGN.md`; it must still enforce the existing contract.
+- Migrate every legacy hardcoded blue CTA unless the owning surface is being updated. Broad migrations belong in separate design-system-scoped PRs.
 
 ## Reference map
 
 | File | What it covers |
 |---|---|
-| `reference/kilo-brand.md` | Kilo-specific tokens, components, rules. Load first, always. |
+| Root `DESIGN.md` | Canonical token contract and application rules. Load first, always. |
+| `reference/kilo-brand.md` | Kilo-specific implementation guidance. Load after `DESIGN.md`, always. |
 | `reference/typography.md` | Inter/mono usage, hierarchy, tabular nums, OpenType polish. |
-| `reference/color-and-contrast.md` | OKLCH tokens, brand vs action color, dark-first contrast rules. |
+| `reference/color-and-contrast.md` | Exact palette, brand vs action color, dark-first contrast rules. |
 | `reference/spatial-design.md` | Spacing, radius scale, grid patterns, optical alignment. |
 | `reference/motion-design.md` | Durations, easings, reduced motion, Kilo brand flourishes. |
 | `reference/interaction-design.md` | Focus, forms, overlays, destructive actions, keyboard nav. |

.agents/skills/kilo-design/reference/color-and-contrast.md

@@ -5,8 +5,7 @@
 
 ## Kilo application
 
-Kilo's palette is already expressed in OKLCH CSS variables. Do not
-introduce a parallel palette.
+Kilo's exact hex palette is defined in root `DESIGN.md` and implemented as CSS variables. Do not introduce a parallel palette or derive replacement values in another color space.
 
 ### Use tokens, not hex
 
@@ -18,9 +17,7 @@ Tailwind bindings are in the `@theme inline` block.
 
 ### Primary and brand accent use
 
-`--brand-primary` / `text-brand-primary` / `bg-brand-primary` (electric
-yellow-green, `oklch(95% 0.15 108)`) is the same swatch as the semantic
-`primary` token. It is both brand and primary action color. Hold it under
+`--brand-primary` / `text-brand-primary` / `bg-brand-primary` (`#F7F586`) is the same swatch as the semantic `primary` token. It is both brand and primary action color. Hold it under
 10% of pixel weight on any given surface. Reserve for:
 
 - Logo, wordmark, and logo-adjacent affordances.
@@ -40,10 +37,10 @@ Do **not** use yellow-green as:
 
 The primary product CTA is the brand yellow-green semantic token:
 
-- Background `primary` / `--brand-primary` / `oklch(95% 0.15 108)`
-- Foreground `primary-foreground` (near-black)
-- Hover: slightly darker yellow-green
-- Focus ring: semantic `ring` or low-alpha yellow-green
+- Background `primary` / `--brand-primary`: `#F7F586`
+- Foreground `primary-foreground`: `#1F1F1F`
+- Hover `primary-hover`: `#E6E475`
+- Focus ring `ring` / `brand-primary-ring`: `#F7F58659`
 
 Hardcoded blue buttons (`#2B6AD2`, Tailwind `blue-*` fills) are legacy drift.
 Migrate them to `primary` when touching the owning component or flow. Blue is
@@ -80,40 +77,29 @@ tree actually react to theme changes.
 
 ---
 
-## Color Spaces: Use OKLCH
+## Color-space discipline
 
-OKLCH is perceptually uniform — equal steps in lightness look equal. HSL
-is not. Kilo's tokens are already OKLCH.
-
-`oklch(lightness chroma hue)` where lightness is 0–100%, chroma ~0–0.4,
-hue 0–360. Hold chroma+hue roughly constant and vary lightness to build
-variants, but **reduce chroma as lightness approaches 0 or 100** — high
-chroma at the extremes reads as garish.
+The canonical palette uses exact hex values. Do not convert tokens to OKLCH, HSL, or generated shades during feature work: conversion and interpolation can alter contract values. Color-space experiments belong in an explicit design-system change that updates `DESIGN.md` first.
 
 ## Building Functional Palettes
 
-### Tinted Neutrals
+### Neutral surfaces
 
-Pure gray is dead. Add a tiny chroma value (0.005–0.015) to neutrals,
-hued toward the brand hue. Kilo already does this: `--color-kilo-gray`
-is `oklch(0.24 0.007 1)`. Tailwind's shadcn neutral tokens carry 0
-chroma; that's acceptable for the dense product shell, but when you
-create a new branded surface, lean on `kilo-gray` rather than a pure gray.
+Use the six exact surface tokens rather than deriving tinted neutrals: inset `#101010`, background `#151515`, raised `#202020`, overlay `#333333`, hover `#3A3A3A`, and selected `#454545`. `kilo-gray` aliases exist for compatibility, not as permission to invent additional neutrals.
 
-### Palette Structure
+### Palette structure
 
-A complete system needs:
+Kilo's complete system already provides:
 
 | Role | Purpose | Example |
 |---|---|---|
 | **Brand** | Rare, voice-carrying accent | 1 color, 1–2 shades |
 | **Action** | Primary call-to-action | 1 color, 3 states |
 | **Neutral** | Text, backgrounds, borders | 9–11 shade scale |
-| **Semantic** | Success, error, warning, info | 4 colors, 2–3 shades each |
-| **Surface** | Cards, modals, overlays | 2–3 elevation levels |
+| **Semantic** | Fixed status domains | Eight families, four shades each |
+| **Surface** | Inset, canvas, cards, overlays, interaction states | Six fixed roles |
 
-Skip secondary/tertiary unless you need them. Most apps work fine with
-one accent and one action color.
+Do not extend this structure from a feature component. Update `DESIGN.md` first when a genuinely new role is required.
 
 ### The 60-30-10 Rule (Applied Correctly)
 
@@ -137,9 +123,7 @@ That shared role should still stay near 10% visual weight.
 | Large text (18px+ or 14px bold) | 3:1 | 4.5:1 |
 | UI components, icons | 3:1 | 4.5:1 |
 
-The gotcha: placeholder text still needs 4.5:1. Check Kilo's
-`placeholder:text-muted-foreground` against `bg-input/30` on real screens
-before lowering opacity further.
+Placeholder text still needs 4.5:1. Check `placeholder:text-muted-foreground` against canonical `bg-input-background`; do not apply another opacity modifier to the already translucent input background.
 
 ### Dangerous Color Combinations
 
@@ -165,10 +149,7 @@ Don't trust your eyes. Use:
 
 ### Dark Mode Is Not Inverted Light Mode
 
-Kilo is dark-first for a reason. If you design something for light mode
-first and "flip" it, you'll introduce bad shadows, under-contrast accents,
-and oversaturated hues. Design on the real `background` / `card` /
-`muted` surfaces, not on `#fff`.
+Kilo is dark-first for a reason. If you design something for light mode first and "flip" it, you'll introduce bad shadows, under-contrast accents, and oversaturated hues. Design on the exact `surface.background`, `surface.raised`, `surface.overlay`, `surface.hover`, and `surface.selected` roles, not on `#fff`.
 
 | Light mode principle | Dark mode behavior |
 |---|---|
@@ -177,23 +158,18 @@ and oversaturated hues. Design on the real `background` / `card` /
 | Vibrant accents | Desaturate accents slightly |
 | White backgrounds | Never pure black — dark gray (OKLCH 12–18%) |
 
-Depth in dark mode comes from surface lightness, not shadow. Kilo's scale
-is already: `background` → `card`/`popover` → `muted`/`secondary`/`accent`.
+Depth in dark mode comes from surface roles, not shadow: `surface.inset` → `surface.background` → `surface.raised` → `surface.overlay`, with `surface.hover` and `surface.selected` reserved for interaction states.
 
 ### Token Hierarchy
 
-Use two layers: primitive tokens (`--blue-500`) and semantic tokens
-(`--color-primary: var(--blue-500)`). In Kilo, primitives live inline in
-OKLCH; semantic tokens map through `@theme inline`. Redefine the semantic
-layer for theme changes, never the primitive layer per component.
+Use two layers: contract primitives such as `--status-blue-500` and semantic aliases such as `--primary`, `--card`, and `--popover`. Tailwind mappings live in `@theme inline`. Components consume semantic or role-specific utilities; they never redefine primitives locally.
 
 ## Alpha Is A Design Smell
 
 Heavy use of transparency (`rgba`, `hsla`) usually means an incomplete
 palette. Alpha creates unpredictable contrast, performance overhead, and
 inconsistency. Define explicit overlay colors for each context instead.
-Kilo's borders use `oklch(1 0 0 / 10%)` deliberately; that's fine. Don't
-stack five more alpha layers on top of it.
+Kilo's `border.default` (`#FFFFFF1A`) and `border.strong` (`#FFFFFF2E`) use deliberate alpha. Do not stack additional alpha layers on top.
 
 ---