diff --git a/.plans/kilo-design-system-execution-checklist.md b/.plans/kilo-design-system-execution-checklist.md index ad8da85..38a9d3f 100644 --- a/.plans/kilo-design-system-execution-checklist.md +++ b/.plans/kilo-design-system-execution-checklist.md @@ -1,135 +1,20 @@ -# Kilo Design System — Execution Checklist (Progress Tracker) +# Kilo Design System — Plan Moved To Linear -**Purpose:** the ordered, trackable task list for unifying Kilo's look & feel across products. -Pair this with the rationale in `kilo-design-system-foundation.md`. This file is the *what & when*; -that file is the *why*. +Linear is the canonical project plan for Kilo Design: -**Owner:** Iván (Design). **Contributors:** per-task below. **Updated:** _set on each edit_. +https://linear.app/vheissu/project/kilo-design-30d3263d297a -### How to read this -- Work top to bottom. Milestones are gated — don't start a milestone until its predecessor's - "Exit criteria" are met (except where marked _parallel-ok_). -- Each task has an ID (`T#.#`), an acceptance check, and dependencies. -- Update the **Status** marker as you go. +Use the Linear project description for the big-picture sequence and the Linear issues for current status. -### Status legend -`☐` not started · `◐` in progress · `☑` done · `⏸` blocked · `▷` parallel-ok +This file is intentionally no longer an active checklist. It remains only as a stable pointer for older references. -### Step progress (fill in as you go — mirrors Linear VVV-118…125) +## Current simplified sequence -|Step |Name |Goal |Status |Target | -|---|---|---|---|---| -|1 |Lock decisions & stop the context bloat |Decisions locked; path-scoped trigger |◐ |Week 1 | -|2 |Tokens + fix the cloud styles |One source of values; cloud code matches it |☐ |Week 1-2 | -|3 |Build the design skill & ship it |Installable `kilo-design-core` + `-cloud` |☐ |Week 2 | -|4 |Fix the core components |Recipes + migrations (cloud) |☐ |Week 3-4 | -|5 |Roll out to Landing |Landing consumes tokens + skill |☐ |Week 4 | -|6 |Roll out to the VS Code panel (+ Console) |Editor + Console skills |☐ |Week 5-6 | -|7 |Roll out to JetBrains, CLI & Mobile |Sub-overlays + mobile skill; light mode removed |☐ |Week 6-7 | -|8 |Keep it from drifting |Governance A→B→C |☐ |Ongoing | +1. Tokens — done. +2. Skills — now. +3. Cloud proof — next. +4. Other products — later. ---- +## Current next issue -> **Granularity:** one line per logical unit, mirroring the 8 Linear steps (VVV-118…125). -> Decisions are settled — see `docs/adr/0001-0010`. Each line carries a definition of done (DoD). - -## Step 1 / M0 — Lock decisions & stop the context bloat -- `☑` **T0.1 Decisions locked.** ADRs 0001-0010 exist in `docs/adr/`. _DoD: done._ -- `☐` **T0.2 Path-scoped trigger (kilo-cloud).** Remove the unconditional "touch UI → read - DESIGN.md" mandate from `AGENTS.md` + `apps/web/AGENTS.md`; replace with ONE pointer keyed on - **file path** (`apps/web/src/**`), never the word "design"; keep `/kilo-design`. _(ADR 0008.)_ - _DoD: a non-UI task no longer auto-loads design docs; the pointer fires only on UI paths._ - -## Step 2 / M1 — Tokens + fix the cloud styles -> Repo was clean-slated (Option A): only `README.md`, `CONTEXT.md`, `docs/adr/`, `.plans/` remain. -> Old token values recoverable from git commit `acdcc60`. -- `☑` **T1.1 Author `tokens.json`** (hand-authored **hex** source). `primary` === `brand` === - `#EDFF00`, `--primary-foreground` = `#1F1F1F`; split into **brand+status (mode-agnostic)** vs - **dark surface neutrals**; include status domain→color map, type scale (Inter + Roboto Mono), - spacing, radius. _(ADR 0003, 0005, 0009.)_ _DoD: `tokens.json` exists and matches the ADRs._ -- `☑` **T1.2 Build the generator** (`build/` + `culori`): emits `tokens.web.css` (OKLCH, web), - `tokens.ts` (hex, portable), `tokens.host-map.md` (incl. the `--vscode-*` mapping); own - `package.json` + a **CI staleness check**. _(ADR 0003, 0010.)_ _DoD: `node build` regenerates - all three; CI fails if artifacts drift from source._ -- `☐` **T1.3 Reconcile cloud `globals.css`** to the tokens: `--primary` = brand yellow + near-black - foreground, fix the font wiring (drop dead `--font-geist-*`), remove the light-mode `:root` leak. - _(ADR 0001, 0005, 0009.)_ _DoD: DriftAudit token/font + "Primary action color" rows read Aligned._ - -## Step 3 / M2 — Build the design skill & ship it to the repos -- `☐` **T2.1 Verify private-repo skill-sync** (the one open prerequisite — do first). _(Risk note.)_ - _DoD: confirmed sync from a private Kilo repo, or blocker escalated to eng._ -- `☐` **T2.2 Build `kilo-design-core` + `kilo-design-cloud`.** Core = brand + voice + router - (router lives in `SKILL.md`: smallest useful source, ≤3 files, else stop and explain). Cloud = - "load core first" + cloud overlay + `patterns/cloud-web/**`. _(ADR 0004, 0008.)_ _DoD: both - skills exist; core authored once._ -- `☐` **T2.3 Publish + adopt in `kilo-cloud`.** Publish both from the repo (`cloudflare/skills` - pattern); add to `skills-lock.json` (guidance → `.agents/`, token values → `src/`); delete the - old local skill + root `DESIGN.md` (do not recreate). _(ADR 0002, 0008.)_ _DoD: installed via - lockfile; old skill + 390-line `DESIGN.md` gone._ -- `☐` **T2.4 Pass the proof gate** for `primary-actions` + `tabs`. _(Proof gate.)_ _DoD: a fresh - agent loads ≤3 files and copies the Canonical Example; one real merged PR per recipe._ - -## Step 4 / M3 — Fix the core components _(ordered by drift severity)_ -> Per-component pattern: recipe (points at ONE Canonical Example) → migrate worst offenders → -> Storybook story → flip the `DriftAudit` row. Recipes earn their place by drift (promotion rule), -> so beyond the two proof-gate recipes the rest are seeded as drift demands — not exhaustively. -- `☐` **T3.1 Button / primary actions** (worst drift; needs T1.3). Finalize the recipe (brand - yellow; one primary per surface, all else secondary/outline/ghost); migrate `ui/button.tsx` + - legacy `Button.tsx` off blue `#2B6AD2`. _DoD: recipe → one impl; Button stickersheet Chromatic - green; DriftAudit button rows Aligned._ -- `☐` **T3.2 Tabs.** Finalize the recipe (segmented vs underline); extract a shared variant on - `ui/tabs.tsx`; migrate 1-2 admin surfaces. _DoD: one canonical tab impl; Storybook green._ -- `☐` **T3.3 Seed badges / alerts / dialogs as drift earns them** (promotion rule): status badges - (`/20` + ring + `text-400`), alerts/banners (`/20`, no colored button fills), dialogs (overlay, - max-widths, footer order, destructive-only). _DoD: each recipe that exists points at one impl - and its DriftAudit row is Aligned._ - -## Step 5 / M4 — Roll out to Landing -- `☐` **T4.1 Adopt in `kilo-landing`.** Install `kilo-design-core` + `kilo-design-landing`; consume - `tokens.web.css`; delete `kilo-landing/DESIGN.md` (don't recreate) + add the path-scoped pointer. - _(ADR 0008.)_ _DoD: landing installs the skills, consumes tokens, keeps no parallel rules._ -- `☐` **T4.2 Seed landing recipes only where drift is real** (e.g. CTA, pricing card). _DoD: - recipes exist only for genuinely drifted patterns._ - -## Step 6 / M5 — Roll out to the VS Code panel _(+ Console)_ -- `☐` **T5.1 Webview = Kilo-dark.** Consume `tokens.ts` in the Solid packages - (`@kilocode/kilo-web-ui`/`kilo-ui`/`ui`); render Kilo-dark, brand-yellow accent over host chrome; - **honor VS Code high-contrast only** (don't follow host light theme). _(ADR 0009, 0007.)_ _DoD: - webview renders Kilo-dark from tokens; high-contrast respected._ -- `☐` **T5.2 Build + install `kilo-design-editor`** (`vscode-webview` sub-overlay; recipes name - `@kilocode/kilo-web-ui` components; reuse kilo-code's existing Storybook). Add to - `skills-lock.json` with a pointer for `kilo-vscode/**`. _(ADR 0007.)_ _DoD: editor skill - installed with webview recipes seeded._ -- `☐` **T5.3 Build + install `kilo-design-console`** (its own product; Kilo-dark; consumes - `tokens.web.css`). Pointer for `kilo-console/**`. _(ADR 0007.)_ _DoD: console skill installed._ - -## Step 7 / M6 — Roll out to JetBrains, CLI & Mobile -- `☐` **T6.1 JetBrains + CLI sub-overlays** (on `kilo-design-editor`). JetBrains = thin (tokens + - voice); specifics in `kilo-jetbrains/AGENTS.md` (with Kirill); IntelliJ + ANSI mappings in - `tokens.host-map.md`. _(ADR 0006, 0007.)_ _DoD: both sub-overlays exist with host token mappings._ -- `☐` **T6.2 Build + install `kilo-design-mobile`; remove the incidental light mode.** Consume - `tokens.ts` (dark only) in `apps/mobile`; coordinate with the mobile dev. _(ADR 0009.)_ _DoD: - mobile skill installed and the light mode removed._ - -## Step 8 / M7 — Keep it from drifting _(runs continuously from Step 4; A → B → C)_ -- `☐` **T7.1 Stage A (now): manual review.** Iván reviews design-touching PRs; promotion rule live; - `DriftAudit` kept current. _(ADR 0006.)_ _DoD: design PRs reviewed; recipes earned by drift._ -- `☐` **T7.2 Stage B/C triggers.** When manual review/hand-bumping is a bottleneck: automate the - Chromatic + DriftAudit gate, version `tokens.json` (semver) with a Renovate-style bot, and hand - product skills to team champions (Iván keeps Core). _(ADR 0006, 0010.)_ _DoD: triggers wired so - automation/champions activate on bottleneck._ - ---- - -## Dependency map (quick reference) -- All decisions are locked (ADRs 0001-0010); nothing is gated on an open decision. -- **Step 2** can start now (tokens authored from the ADRs). -- **Step 3** depends on Step 2 + **T2.1** (private-repo skill-sync verified — the one open risk). -- **Step 4** depends on Step 2 (tokens) + Step 3 (skills installed); **T3.1** depends on **T1.3**. -- **Steps 5-7** depend on **Step 3 proven in cloud** (the proof gate, **T2.4**); ordered - cloud → landing → editor/console → jetbrains/cli/mobile. -- **Step 8** runs continuously from Step 4 onward. - -## Out of scope (explicitly, to avoid scope creep) -- Figma-to-code token pipeline. A global multi-product Storybook. Rewriting all legacy blue CTAs - at once (migrate as surfaces are touched). Enforcement automation beyond Chromatic + review. +`VVV-131` — Verify private-repo skill-sync. diff --git a/.plans/kilo-design-system-foundation.md b/.plans/kilo-design-system-foundation.md index 8873753..9979df6 100644 --- a/.plans/kilo-design-system-foundation.md +++ b/.plans/kilo-design-system-foundation.md @@ -1,5 +1,10 @@ # Kilo Design System Foundation — Plan +> Archived background rationale. Linear is the canonical active project plan: +> https://linear.app/vheissu/project/kilo-design-30d3263d297a +> This archive contains superseded pre-pilot references to `kilo-design-core`; ADR 0011 and Linear +> are current. + Owner: Iván (solo design, product-led). Audience: ~20 engineers + their agents. Scope: kilo-design (canonical), kilo-cloud, kilo-code (extensions/CLI/JetBrains/webview), kilo-landing, kilo-cloud mobile. Status: proposal for review. Not started. diff --git a/CONTEXT.md b/CONTEXT.md index 49c02ef..b4c3859 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -6,13 +6,13 @@ A design system shaped for both people and AI agents. It includes canonical design language, tokens, reusable pattern recipes, and loading rules that help agents choose the right context without filling the session with unrelated design material. -### Core Skill +### Product-Facing Core -The single installable skill (`kilo-design-core`) that carries the shared Kilo design language, voice, token meaning, and the Context Router. Installed once by anyone doing Kilo UI; authored exactly once. Every Product Skill instructs the agent to load it first. +The product-consumable center of the design system: `tokens.json` plus generated artifacts in `src/` (`tokens.web.css`, `tokens.ts`, `tokens.host-map.md`). This is the current core. A standalone `kilo-design-core` runtime skill is deferred until a second product skill proves reuse. ### Product Skill -A small installable skill per product family (`kilo-design-cloud`, `-landing`, `-mobile`, `-console`, `-editor`) containing only that product's Product Overlay and Pattern Recipes. Depends on the Core Skill by convention (its `SKILL.md` says "load `kilo-design-core` first"), not by a tool-enforced dependency. A "family" is decided by theming contract (who owns the colors), not by which code library a surface imports. +A small installable skill per product family. The current pilot is `kilo-design-cloud`; future candidates include `-landing`, `-mobile`, `-console`, and `-editor`. A product skill contains that product's Product Overlay, internal agent references, and Pattern Recipes. A "family" is decided by theming contract (who owns the colors), not by which code library a surface imports. _Avoid_: "design plugin", "product pack". ### Host Sub-overlay @@ -36,9 +36,9 @@ A short set of loading rules that tells an agent which design files to read for The single narrow line in a repo's existing AGENTS.md that points the agent at the design skill based on **which file is being edited** (e.g. a UI screen under `apps/web/src/**`), never on the keyword "design." It carries no design rules — only the pointer. It is what stops the old keyword-triggered over-loading. _Avoid_: a `DESIGN.md` file in a product repo (rules live only in the skill; never recreate it). -### Evolving Pilot +### Cloud Pilot Skill -A deliberately incomplete design-system slice that proves a format through real product work before expanding. Cloud web is the current evolving pilot. +The first agent-facing adapter, published as `kilo-design-cloud`. It proves the skill format with Cloud web before any standalone core skill or other product skill is created. ### Product Overlay @@ -56,5 +56,5 @@ The gap between shipped product code and the canonical design system. Values can ### Primary (brand action color) -The neon yellow-green (`#EDFF00`). In Kilo, primary and brand are the **same token** — the primary action color is the brand color, because the suite is dark-first and the neon is the identity. Used for the one primary action per surface, plus atmospheric brand roles (logo tile, focus ring, glow). Scarcity is enforced by the `primary-actions` recipe, not by making the token neutral. +The brand yellow-green (`#F7F586`). In Kilo, primary and brand are the **same token** — the primary action color is the brand color, because the suite is dark-first and the yellow-green is the identity. Used for the one primary action per surface, plus atmospheric brand roles (logo tile, focus ring, glow). Scarcity is enforced by the `primary-actions` recipe, not by making the token neutral. _Avoid_: a neutral/gray primary; "accent" as a synonym for primary. diff --git a/README.md b/README.md index fd10ffe..dbd7c1f 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,18 @@ Canonical source of truth for Kilo's design system across products including Cloud, Landing, Console, VS Code, JetBrains, CLI, and Mobile. -This repository currently contains the first implementation slice of the design system: the hand-authored token contract, generated token artifacts, and a local playground for reviewing and tuning tokens visually. +This repository currently contains the first implementation slice of the design system: the hand-authored token contract, generated token artifacts, the Cloud pilot skill, and a local playground for reviewing and tuning tokens visually. ## What Lives Here - `tokens.json` is the canonical design token source for the current dark-first Kilo design language. - `src/` contains generated token artifacts for product consumption. +- `kilo-design-cloud/` is the Cloud pilot skill for agents. - `build/` contains the token generator used by humans, the playground, and CI. - `playground/` is a local Next.js app for previewing, editing, and saving `tokens.json`. - `CONTEXT.md` defines the shared glossary for the design-system architecture. - `docs/adr/` records the locked architecture decisions behind the system. -- `.plans/` contains the foundation plan and execution checklist for future work. +- `.plans/` contains archived planning rationale and a pointer to the canonical Linear project plan. ## Token Contract @@ -47,6 +48,22 @@ This regenerates: CI runs the same command and fails if regenerated artifacts differ from the committed files. That keeps `tokens.json` and `src/` in sync. +## Installable Skill + +This repo currently publishes one pilot skill from a top-level folder, following the `npx skills` discovery model. + +- `kilo-design-cloud` applies the Cloud overlay, internal agent references, and pilot recipes. +- The design-system core for products is `tokens.json` plus generated artifacts in `src/`, not a runtime skill. +- ADRs, Linear, and `.plans/` are scaffolding for creating the skill, not daily product guidance. + +Validate local skill discovery with: + +```bash +npx skills@latest add . --list --full-depth --yes +``` + +Expected result today: one discovered skill, `kilo-design-cloud`. Other product skills are intentionally not built yet. + ## Run The Playground From the repository root: @@ -95,10 +112,10 @@ The write-back API is local-development only and refuses token reads or writes w Read these before changing the design-system direction: -1. `CONTEXT.md` for glossary terms such as Core Skill, Product Skill, Product Overlay, Pattern Recipe, Canonical Example, and Drift. +1. `CONTEXT.md` for glossary terms such as Product-Facing Core, Product Skill, Product Overlay, Pattern Recipe, Canonical Example, and Drift. 2. `docs/adr/` for the settled decisions and their reasoning. -3. `.plans/kilo-design-system-foundation.md` for the strategy behind the design-system architecture. -4. `.plans/kilo-design-system-execution-checklist.md` for the task-by-task implementation plan. +3. Linear project `Kilo Design` for the active big-picture plan and current status: https://linear.app/vheissu/project/kilo-design-30d3263d297a +4. `.plans/kilo-design-system-foundation.md` only for archived background rationale. ## What Does Not Live Here diff --git a/docs/adr/0004-skill-packaging-core-plus-product.md b/docs/adr/0004-skill-packaging-core-plus-product.md index 4c496f0..040b3d3 100644 --- a/docs/adr/0004-skill-packaging-core-plus-product.md +++ b/docs/adr/0004-skill-packaging-core-plus-product.md @@ -1,5 +1,7 @@ # Skill packaging: a shared Core Skill + thin Product Skills, composed by convention +Status: Superseded by ADR 0011 for the Cloud pilot. The shared-core concept is deferred; the first shipped runtime skill is `kilo-design-cloud`. + The design guidance ships as **multiple skills published from the one `kilo-design` repo** (the same way `cloudflare/skills` exposes `durable-objects`, `wrangler`, … from one repo): diff --git a/docs/adr/0005-primary-is-brand-yellow.md b/docs/adr/0005-primary-is-brand-yellow.md index 22b99b0..2c69cdd 100644 --- a/docs/adr/0005-primary-is-brand-yellow.md +++ b/docs/adr/0005-primary-is-brand-yellow.md @@ -1,9 +1,9 @@ # Primary action color is the brand yellow-green (primary and brand are one token) -The Kilo suite is dark-first, and the neon yellow-green is the brand's defining accent. A +The Kilo suite is dark-first, and the brand yellow-green is the brand's defining accent. A neutral/gray primary reads as dead and generic in dark mode, so **`--primary` *is* the brand color** — primary and brand are the same token, exactly as `tokens.json` already encodes -(`primary` === `brand` === `#EDFF00`), with near-black `--primary-foreground` (`#1F1F1F`) for +(`primary` === `brand` === `#F7F586`), with near-black `--primary-foreground` (`#1F1F1F`) for AA contrast. shadcn's default button variant carries it. Consequence: cloud's current neutral `--primary` (`oklch(0.922 0 0)`) is **Drift** to be diff --git a/docs/adr/0006-governance-starts-manual-then-graduates.md b/docs/adr/0006-governance-starts-manual-then-graduates.md index 1695971..31cda93 100644 --- a/docs/adr/0006-governance-starts-manual-then-graduates.md +++ b/docs/adr/0006-governance-starts-manual-then-graduates.md @@ -1,5 +1,7 @@ # Governance starts manual (A), graduates to automation (B), then champions (C) +Status: Accepted. Note: per ADR 0011, current ownership is of product-facing assets and the Cloud pilot skill; a standalone core skill is deferred. + To stay lean, the design system **starts with manual review**: Iván reviews design-touching PRs directly, rather than standing up Chromatic gates, `DriftAudit` enforcement, and per-team ownership before the system even exists. @@ -12,7 +14,7 @@ This is a deliberate staged model, not a permanent state. The graduation trigger automatically; human review narrows to `kilo-design` changes (tokens, core, recipes) and net-new patterns flagged as recipe candidates. - **B → C (per-team champions):** when product teams have stable ownership and each can own its - Product Skill while Iván owns the Core Skill. + Product Skill while Iván owns the product-facing core assets. Risk: A is a bottleneck and the system can rot if the triggers are ignored. This ADR exists so that "A forever" is recognized as a failure mode, and the move to B is expected, not optional. diff --git a/docs/adr/0007-product-skill-granularity-and-host-sub-overlays.md b/docs/adr/0007-product-skill-granularity-and-host-sub-overlays.md index 27d332d..f35a17b 100644 --- a/docs/adr/0007-product-skill-granularity-and-host-sub-overlays.md +++ b/docs/adr/0007-product-skill-granularity-and-host-sub-overlays.md @@ -1,5 +1,7 @@ # Product-skill granularity, the editor family, and component-library sharing +Status: Partially superseded by ADR 0011 for sequencing. Product-skill granularity still stands, but `kilo-design-core` is deferred until a second product skill proves reuse. + Refines ADR 0004. The unit of a Product Skill is a **product family**, decided by **theming contract** (who owns the colors), not by which code library a surface happens to import. @@ -9,8 +11,8 @@ Granularity rule: - **Multi-host family** → one Product Skill with **host sub-overlays**, one per theming contract, selected by the router. -Product skills (alongside `kilo-design-core`): `kilo-design-cloud`, `kilo-design-landing`, -`kilo-design-mobile`, `kilo-design-console`, and `kilo-design-editor`. +Current product skill: `kilo-design-cloud`. Future product skills may include +`kilo-design-landing`, `kilo-design-mobile`, `kilo-design-console`, and `kilo-design-editor`. ## The editor family diff --git a/docs/adr/0008-loading-path-scoped-no-design-md.md b/docs/adr/0008-loading-path-scoped-no-design-md.md index bc94240..feba216 100644 --- a/docs/adr/0008-loading-path-scoped-no-design-md.md +++ b/docs/adr/0008-loading-path-scoped-no-design-md.md @@ -1,5 +1,7 @@ # Loading design context: rules live only in the skill, triggered by file path, no per-repo DESIGN.md +Status: Partially superseded by ADR 0011 for the Cloud pilot. Path-scoped loading still stands; Cloud installs the single `kilo-design-cloud` pilot skill for now. + Design rules live in **one place only — the skill** — and load on demand. No product repo keeps a `DESIGN.md`. The old 390-line `DESIGN.md` is deleted and **not recreated** (not even as a tiny "pointer" file): rules-in-repo-files attract growth, and that file — loaded by an always-on, @@ -8,8 +10,9 @@ task pulled in design.md" failure). Loading is governed by three layered levers, **none keyed on the word "design"**: -1. **Per-repo install scoping.** A repo installs only `kilo-design-core` + its product skill(s). - An agent cannot load another product's rules because they are not present. +1. **Per-repo install scoping.** A repo installs only its relevant product skill(s). For the + Cloud pilot, that means `kilo-design-cloud` only. An agent cannot load another product's rules + because they are not present. 2. **Path-scoped trigger.** A single narrow line in the repo's *existing* AGENTS.md points to the skill when UI files are edited (e.g. `apps/web/src/**/*.tsx`, component/style dirs) — never on the keyword "design." This fixes both failure modes: backend tasks don't match (no diff --git a/docs/adr/0011-cloud-pilot-skill-before-core-skill.md b/docs/adr/0011-cloud-pilot-skill-before-core-skill.md new file mode 100644 index 0000000..0754b19 --- /dev/null +++ b/docs/adr/0011-cloud-pilot-skill-before-core-skill.md @@ -0,0 +1,22 @@ +# Cloud pilot skill before a standalone core skill + +Status: Accepted. Supersedes the runtime-skill packaging parts of ADR 0004, ADR 0007, and ADR 0008. + +The design-system core for products is **not** a standalone runtime skill yet. The product-facing core is: + +- `tokens.json` +- `src/tokens.web.css` +- `src/tokens.ts` +- `src/tokens.host-map.md` + +ADRs, Linear, and `.plans/` are scaffolding for creating the skills. They are not daily product guidance for agents working in product repos. + +The first agent-facing adapter is one pilot skill: + +- `kilo-design-cloud` + +It contains the Cloud overlay, internal references, and the first two Cloud recipes. A standalone `kilo-design-core` skill is deferred until a second product skill proves real reuse. + +Why: publishing a core skill before the Cloud pilot makes the abstraction feel like the product's daily driver, adds an unenforced dependency between skills, and increases install/load complexity before reuse is proven. Keeping the first adapter Cloud-specific tests the format with less machinery while preserving an extraction path later. + +When a second product skill starts, extract the stable shared references from `kilo-design-cloud/reference/` into a shared core skill or a generated source bundle. diff --git a/kilo-design-cloud/SKILL.md b/kilo-design-cloud/SKILL.md new file mode 100644 index 0000000..97a447b --- /dev/null +++ b/kilo-design-cloud/SKILL.md @@ -0,0 +1,46 @@ +--- +name: kilo-design-cloud +description: Kilo Cloud web UI overlay and pilot pattern recipes. Use when editing or reviewing Kilo Cloud UI paths such as apps/web/src/**, apps/storybook/**, or when the Cloud repo path-scoped trigger requests Kilo design guidance. +--- + +# Kilo Design Cloud + +This is the first agent-facing adapter for the Kilo design system. It covers Kilo Cloud's web app, Storybook design-system stories, and the first Cloud pattern recipes. + +## Run Order + +1. Read the target Cloud file first. For components, also read the matching primitive in `apps/web/src/components/ui/` and any Storybook story. +2. Load `overlay.md` for all Cloud UI work. +3. Load one internal reference only when the task needs it: product judgment, brand, token architecture, or voice. +4. Load at most one matching recipe unless the task clearly spans multiple patterns. +5. If no recipe exists, use the overlay plus current Cloud code and report a coverage gap. +6. Keep broad product cleanup out of focused tasks. + +Completion criterion: the answer or change names the loaded overlay/recipe, follows real Cloud code, and does not normalize unrelated UI. + +## Recipe Router + +| Prompt or file signal | Load | +| --- | --- | +| primary action, CTA, button hierarchy, blue button drift | `patterns/cloud-web/primary-actions.md` | +| tabs, segmented navigation, Radix tabs, active tab state | `patterns/cloud-web/tabs.md` | +| tokens, globals.css, semantic mapping | `reference/token-architecture.md`; record that Cloud token adoption is `VVV-130` | +| copy, empty states, labels, errors, confirmations | `reference/voice.md` | +| badges, alerts, dialogs, sidebar, empty states | `overlay.md`; report coverage gap if a rule is missing | + +## Non-Goals + +- Do not build Landing, Editor, Console, Mobile, JetBrains, or CLI guidance here. +- Do not recreate a Cloud `DESIGN.md`. +- Do not migrate every hardcoded blue button unless the task is `primary-actions` implementation. +- Do not invent recipes without a real Canonical Example in shipped Cloud code. + +## Reference Map + +- `overlay.md`: Cloud product overlay and known drift. +- `reference/product-judgment.md`: modes, authority order, and coverage gaps. +- `reference/brand.md`: Cloud use of Kilo brand language. +- `reference/token-architecture.md`: how Cloud agents should read product-facing token artifacts. +- `reference/voice.md`: Kilo Cloud UI copy rules. +- `patterns/cloud-web/primary-actions.md`: primary CTA and button hierarchy recipe. +- `patterns/cloud-web/tabs.md`: Cloud tab recipe. diff --git a/kilo-design-cloud/overlay.md b/kilo-design-cloud/overlay.md new file mode 100644 index 0000000..3590b7b --- /dev/null +++ b/kilo-design-cloud/overlay.md @@ -0,0 +1,71 @@ +# Kilo Cloud Overlay + +Cloud is the pilot product for Kilo's agent-consumable design system. It is a dense, dark-first infrastructure console built with Next.js, React, Tailwind, shadcn/ui, Radix, and `lucide-react`. + +## Product Intent + +- Help teams understand workspaces, billing, subscriptions, KiloClaw, and operational status without marketing noise. +- Stay compact and task-oriented. Cloud can be visually polished, but it should not feel like a landing page. +- Make one action obvious per surface. Surrounding actions should be secondary, ghost, outline, or links. + +## Code Sources To Read First + +| Concern | Cloud path | +| --- | --- | +| Base theme and Tailwind tokens | `apps/web/src/app/globals.css` | +| Font variables | `apps/web/src/app/layout.tsx` | +| shadcn config | `apps/web/components.json` | +| UI primitives | `apps/web/src/components/ui/*.tsx` | +| Legacy button drift | `apps/web/src/components/Button.tsx` | +| Drift audit | `apps/storybook/stories/design-system/DriftAudit.stories.tsx` | + +## Token Mapping + +Use semantic roles, not raw values: + +| Role | Cloud token | +| --- | --- | +| Page background | `--background` / `bg-background` | +| Default text | `--foreground` / `text-foreground` | +| Raised surface | `--card`, `--popover` | +| Secondary surface | `--secondary`, `--muted`, `--accent` | +| Muted text | `--muted-foreground` | +| Primary action | `--primary` / `bg-primary` | +| Primary action text | `--primary-foreground` / `text-primary-foreground` | +| Border and focus | `--border`, `--input`, `--ring` | + +Known drift: Cloud token adoption is tracked by `VVV-130`. Until that lands, recipe guidance should still point agents at semantic roles, not hardcoded replacements. + +## Cloud Rhythm + +- Controls are compact: `h-8`, `h-9`, `h-10`; icons are usually `size-4`. +- Cards and dialogs use existing shadcn primitives before custom containers. +- Prefer `gap-*` and grouped spacing over dividers between every row. +- Keep status color as small signals: badges, inline text, rings, or charts. Do not let status hues become the UI palette. +- Use Inter for UI and Roboto Mono for code, identifiers, token names, and tabular data. + +## Cloud Anti-Patterns + +- Blue button fills as primary actions. +- Yellow-green applied to multiple unrelated controls. +- Equal-card dashboard grids when the task has one focal action. +- New component libraries or new design primitives when shadcn/Radix already exists. +- Marketing copy, fake slogans, avatars, decorative AI stars, glass panels, or gradient text inside product UI. +- Large implementation sweeps before the matching recipe exists. + +## Current Coverage + +Covered now: + +- Primary actions. +- Tabs. + +Known gaps: + +- Status badges. +- Alerts and feedback banners. +- Dialogs and destructive confirmations. +- Sidebar/topbar chrome. +- Empty states. + +When a gap appears in real work, use the nearest shipped code and report the missing recipe instead of adding broad rules. diff --git a/kilo-design-cloud/patterns/cloud-web/primary-actions.md b/kilo-design-cloud/patterns/cloud-web/primary-actions.md new file mode 100644 index 0000000..4fdf978 --- /dev/null +++ b/kilo-design-cloud/patterns/cloud-web/primary-actions.md @@ -0,0 +1,44 @@ +# Cloud Web Pattern: Primary Actions + +Pattern ID: `cloud-web.primary-actions` + +## When To Use + +Use this recipe when a Cloud surface has a main CTA, button hierarchy, primary button drift, or hardcoded blue button background. + +## Rule + +Each surface gets one primary action. It uses the semantic primary action role, not a color name. Secondary choices use secondary, outline, ghost, destructive, or link variants. + +## Canonical Example + +Real code to copy: + +- `apps/web/src/components/ui/button.tsx` +- `Button` default variant: `bg-primary text-primary-foreground shadow hover:bg-primary/90` + +Do not copy the current `variant="primary"` implementation in the same file. It is hardcoded blue drift and is tracked for migration. + +## Implementation Rules + +- Use `