sdtk-design-kit 0.2.1 → 0.3.1

package/README.md

@@ -1,160 +1,102 @@
-# SDTK-DESIGN Kit
+# sdtk-design-kit
 
-`sdtk-design-kit` is the standalone SDTK-DESIGN Foundation Beta package.
+`sdtk-design-kit` is the public CLI package for SDTK-DESIGN.
 
-SDTK-DESIGN is a local-first MVP design planner and reviewer for solo founders. It turns a rough MVP idea into reviewable design artifacts and a deterministic handoff for SDTK-CODE.
+Package version in this source snapshot: `0.3.1`
+CLI command: `sdtk-design`
 
-It is not a Figma clone, Lovable clone, v0 clone, full app builder, or production code generator.
+SDTK-DESIGN is a local-first MVP design planner and reviewer. It turns either a rough MVP idea or explicit SDTK-SPEC design artifacts into reviewable design docs, a static prototype, visual review evidence, and an SDTK-CODE handoff.
 
-## Beginner Flow
+It is not a Figma clone, Lovable clone, v0 clone, full app builder, production code generator, or network service.
 
-Use this optimized flow for a clean project:
+## Install
 
-```powershell
+```bash
+npm install -g sdtk-design-kit
+sdtk-design --version
+sdtk-design --help
+```
+
+## Beginner Idea Flow
+
+```bash
 sdtk-design init
-sdtk-design start --idea "I want to build a lightweight CRM for solo consultants to track leads, follow-ups, notes, and simple revenue pipeline without using a complex enterprise CRM." --style premium-dashboard
+sdtk-design start --idea "I want to build a lightweight CRM for solo consultants to track leads." --style premium-dashboard
 sdtk-design prototype
 sdtk-design review --artifact docs/design/prototype/index.html
 sdtk-design handoff
 sdtk-design status
 ```
 
-What each command does:
-
-- `init`: creates the local design workspace.
-- `start`: creates the design brief, screen map, required wireframes, and design system.
-- `prototype`: creates a static visual preview from the generated design artifacts.
-- `review`: reviews a local markdown or static HTML design artifact with visual polish checks.
-- `handoff`: converts the generated design package into SDTK-CODE handoff guidance.
-- `status`: reports complete artifacts, missing artifacts, and the next recommended command.
+## SPEC-Driven Multi-Screen Flow
 
-## Available Commands
+Use this when SDTK-SPEC or an agent has produced explicit screen/design artifacts.
 
-```powershell
-sdtk-design --help
-sdtk-design --version
-sdtk-design init [--project-path <path>] [--force] [--no-state]
-sdtk-design start --idea "<idea>" [--style <preset>] [--project-path <path>] [--force]
-sdtk-design brief --idea "<idea>" [--project-path <path>] [--force]
-sdtk-design screens [--project-path <path>] [--force]
-sdtk-design wireframe --screen landing [--project-path <path>] [--force]
-sdtk-design wireframe --screen all [--project-path <path>] [--force]
-sdtk-design system [--style <preset>] [--project-path <path>] [--force]
-sdtk-design prototype [--style <preset>] [--project-path <path>] [--force]
-sdtk-design review --artifact docs/design/wireframes/LANDING.md [--project-path <path>] [--force]
-sdtk-design review --artifact docs/design/prototype/index.html [--project-path <path>] [--force]
-sdtk-design handoff [--project-path <path>] [--force]
-sdtk-design status [--project-path <path>]
+```bash
+sdtk-design init
+sdtk-design start --from-spec . --profile b2b-commerce
+sdtk-design prototype --force
+sdtk-design review --artifact docs/design/prototype/index.html
+sdtk-design handoff
+sdtk-design status
 ```
 
-## Generated Artifacts
+Optional read-only reference export mapping:
 
-Human-facing output is written under `docs/design/`:
-
-```text
-docs/design/
-  README.md
-  DESIGN_BRIEF.md
-  SCREEN_MAP.md
-  DESIGN_SYSTEM.md
-  DESIGN_HANDOFF.md
-  prototype/
-    index.html
-  wireframes/
-    LANDING.md
-    ONBOARDING.md
-    DASHBOARD.md
-  reviews/
-    DESIGN_REVIEW_YYYYMMDD.md
+```bash
+sdtk-design start --from-spec . --reference-dir ./docs/design/reference-export --profile b2b-commerce
 ```
 
-Internal state may live under `.sdtk/design/`. SDTK-DESIGN must not create or mutate `.sdtk/atlas`.
-
-## Visual Style Presets
-
-`start` and `system` accept `--style <preset>`. If omitted, SDTK-DESIGN uses `minimal-saas`.
-
-Available presets:
-
-- `minimal-saas`: clean solo-founder SaaS default.
-- `premium-dashboard`: dashboard-first MVP with stronger metrics, cards, and status surfaces.
-- `bold-founder`: high-contrast launch style for marketing-heavy MVPs.
-- `warm-editorial`: softer consultant/service-product style.
+`start --from-spec` consumes explicit design artifacts. It does not parse raw requirement prose or invent missing screens.
 
-## Command Details
-
-### `init`
-
-Creates `docs/design/`, `docs/design/wireframes/`, `docs/design/reviews/`, `docs/design/README.md`, and `.sdtk/design/manifest.json`.
-
-Existing managed init files are skipped by default. Use `--force` only when you explicitly want to refresh managed init files. Use `--no-state` to skip `.sdtk/design`.
-
-### `start`
-
-Runs:
+## Commands
 
 ```text
-brief -> screens -> wireframe --screen all -> system
-```
-
-This is the beginner facade for the core design package. It does not run review or handoff. Existing managed core outputs are not overwritten unless `--force` is explicit.
-
-Use `--style premium-dashboard` for dashboard-led MVPs such as ClientPulse.
-
-### `prototype`
-
-Creates a static visual preview at `docs/design/prototype/index.html`.
-
-```powershell
-sdtk-design prototype --style premium-dashboard
-```
-
-The prototype includes landing, onboarding, and dashboard sections with responsive CSS, selected visual preset tokens, and domain copy derived from the generated design artifacts. It is not production app code and does not create files outside `docs/design/prototype`.
-
-### `review`
-
-Reviews a local markdown or static HTML artifact. For the optimized workflow, review the generated prototype:
-
-```powershell
+sdtk-design init
+sdtk-design start --idea "<idea>" --style premium-dashboard
+sdtk-design start --from-spec . --reference-dir ./docs/design/reference-export --profile b2b-commerce
+sdtk-design brief --idea "<idea>"
+sdtk-design screens
+sdtk-design wireframe --screen landing
+sdtk-design system --style minimal-saas
+sdtk-design prototype
 sdtk-design review --artifact docs/design/prototype/index.html
+sdtk-design handoff
+sdtk-design status
 ```
 
-Markdown artifact review remains supported:
+Visual style presets:
 
-```powershell
-sdtk-design review --artifact docs/design/wireframes/LANDING.md
+```text
+minimal-saas
+premium-dashboard
+bold-founder
+warm-editorial
 ```
 
-The review report is written to `docs/design/reviews/DESIGN_REVIEW_YYYYMMDD.md`.
-
-Current review support is local artifact review only. The report includes visual polish checks for hierarchy, spacing/density, CTA clarity, dashboard information density, responsive/mobile risk, accessibility baseline, and anti-wireframe/mockup risk. No URL, browser, screenshot, vision, or DOM review is implemented in Foundation Beta.
-
-### `handoff`
-
-Reads the generated brief, screen map, required wireframes, and design system, then writes `docs/design/DESIGN_HANDOFF.md`.
+## Outputs
 
-The handoff is planning input for SDTK-CODE. It includes screen-to-component mapping, screen-to-user-story mapping, design decisions, implementation notes, suggested data model, domain/status taxonomy, interaction flow, persistence guidance, visual implementation contract, prototype reference, SDTK-CODE build notes, acceptance criteria, and a readiness verdict. Domain-specific examples are derived from the generated artifacts rather than fixed to one demo product. It does not generate production app code.
+Human-facing artifacts are written under `docs/design/`, including:
 
-### `status`
-
-Read-only command. It reports complete artifacts, missing artifacts, and the next recommended command.
-
-The optimized readiness path expects `docs/design/prototype/index.html` before prototype review and handoff.
-
-## Non-Goals And Deferred Features
+```text
+DESIGN_BRIEF.md
+SCREEN_MAP.md
+DESIGN_SYSTEM.md
+DESIGN_HANDOFF.md
+prototype/index.html
+reviews/DESIGN_REVIEW_YYYYMMDD.md
+wireframes/
+```
 
-Foundation Beta does not provide:
+SPEC-driven/high-fidelity flows may also create per-screen briefs, component contracts, visual token contracts, reference maps, fidelity reviews, and internal state under `.sdtk/design/`.
 
-- Figma, Lovable, v0, or full app-builder replacement behavior.
-- Production app code generation.
-- URL, browser, screenshot, vision, or DOM review.
-- Network calls by default.
-- Pro entitlement gates.
-- `.sdtk/atlas` creation or mutation.
-- SDTK-WIKI output mutation.
-- Landing-site updates.
-- npm publish or maintainer packaging checks without separate maintainer approval.
+## Boundaries
 
-## SDTK-CODE Handoff
+- no production app code generation
+- no URL/browser/screenshot/vision review in the CLI
+- no network calls by default
+- no `.sdtk/atlas` creation or mutation
+- no SDTK-WIKI output mutation
+- no overwrite unless a command explicitly supports `--force`
 
-After `sdtk-design handoff`, pass `docs/design/DESIGN_HANDOFF.md` to SDTK-CODE as implementation planning input. SDTK-CODE should still plan, implement, and verify code changes separately.
+See `products/sdtk-design/governance/SDTK_DESIGN_USAGE_GUIDE.md` for the full usage guide.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdtk-design-kit",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Local-first MVP design planner and reviewer for SDTK workspaces.",
   "bin": {
     "sdtk-design": "bin/sdtk-design.js"
@@ -9,6 +9,7 @@
   "type": "commonjs",
   "files": [
     "bin/",
+    "skills/",
     "src/",
     "README.md"
   ],

package/skills/design-prototype/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: design-prototype
+description: Generate high-fidelity standalone HTML prototypes from an SDTK-DESIGN generation manifest, design system, design tokens, and per-screen briefs.
+---
+
+# Design Prototype
+
+Use this skill when the user asks you to generate, regenerate, or polish SDTK-DESIGN prototype screen HTML from `docs/design/prototype/.manifest.json`.
+
+## Inputs
+
+Read these files before writing any screen HTML:
+
+1. `docs/design/prototype/.manifest.json`
+2. This skill's `references/designer-charter.md`
+3. This skill's `references/craft.md`
+4. `docs/design/DESIGN_SYSTEM.md`
+5. `docs/design/DESIGN_TOKENS.json`
+6. Each screen brief named by the manifest entry's `briefPath`
+
+The manifest contract is:
+
+```json
+{
+  "screens": [
+    {
+      "screenId": "home",
+      "title": "Home",
+      "role": "home",
+      "briefPath": "docs/design/screens/home_DESIGN_BRIEF.md",
+      "outPath": "docs/design/prototype/screens/home.html"
+    }
+  ]
+}
+```
+
+## Workflow
+
+1. Validate that the manifest exists and that every screen entry has `screenId`, `title`, `role`, `briefPath`, and `outPath`.
+2. Read the charter and craft references once for the whole run.
+3. Read `DESIGN_SYSTEM.md` and `DESIGN_TOKENS.json` as the only brand and visual-direction authority.
+4. For each screen, read its `briefPath`, plan the page structure, then write exactly one complete standalone `<!doctype html>` document to its `outPath`.
+5. Keep CSS inline in the file. Do not create external CSS, JavaScript, image, or font files.
+6. Keep each generated HTML file under roughly 1000 lines.
+7. Use real brief-sourced content, data slots, states, actions, and screen purpose. Do not add filler sections to make the page feel dense.
+8. Verify each file after writing: complete doctype, `<html>`, `<head>`, `<body>`, non-empty `<title>`, one `<h1>`, visible state coverage, token usage, no raw debug JSON, no placeholder/filler copy.
+
+## NEEDS_* slot rendering convention (BK-227)
+
+When emitting NEEDS_* placeholders in screen HTML, distinguish two slot classes by checking the brief's per-section `interactive_data_slots` array (sidecar JSON) or the `interactive=` detail in the brief markdown:
+
+**Interactive slots** — markers listed in `interactive_data_slots`. These sit inside repeated card / row / list structures (product cards, order rows, search results, category cards, nav items). Emit each as:
+
+    <a href="#" data-needs="NEEDS_PRODUCT_NAME">NEEDS_PRODUCT_NAME</a>
+
+**Static slots** — every other NEEDS_* marker (brand name in header, footer URLs, hero imagery, single-occurrence content). Emit as:
+
+    <span data-needs="NEEDS_BRAND_NAME">NEEDS_BRAND_NAME</span>
+
+Rules:
+- `href="#"` is the ONLY permitted destination for skeleton anchors. Never invent URLs.
+- The visible marker text and the `data-needs` attribute value are identical across both classes — only the wrapper element changes.
+- If a section mixes interactive and static slots, look up class per marker via set membership on `interactive_data_slots`.
+- Skeleton anchors preserve BK-225 honesty (the `data-needs` attribute marks the gap) and BK-217 no-invented-content (`#` is not a real destination).
+
+### Density rule for repeated structures (BK-231)
+
+When a section's `interactive_data_slots` is non-empty (BK-227 interactive) OR the section's `components` include a card / row / list-item / nav-item pattern, render **3–4 sample instances** rather than 1. Each instance reuses the same skeleton anchor + marker set from BK-227.
+
+Cap at 4 instances per section to keep file size bounded (per-screen HTML must stay under ~1000 lines). Single-occurrence interactive slots (e.g. one cart-summary panel, one add-to-cart button on PDP) are unaffected — apply density only to repeated structures.
+
+Composition with BK-229 facts:
+- If `tokens.brand.categories[]` has N entries → render N category instances (use supplied labels per BK-229).
+- For repeated structures NOT bound to factual data (product cards, order rows, search results, generic list items) → render exactly 4 instances, all carrying the same `NEEDS_*` marker set.
+
+#### Examples
+
+Product cards in a category screen — render 4 instances per BK-231 density rule (section.interactive_data_slots contains NEEDS_PRODUCT_NAME, NEEDS_PRODUCT_IMAGE, NEEDS_SKU, NEEDS_PRICE):
+```
+<div class="product-grid">
+  <a href="#" data-needs="NEEDS_PRODUCT_NAME" class="product-card">
+    <span data-needs="NEEDS_PRODUCT_IMAGE" class="product-thumb">NEEDS_PRODUCT_IMAGE</span>
+    <span class="product-name">NEEDS_PRODUCT_NAME</span>
+    <span class="product-sku" data-needs="NEEDS_SKU">NEEDS_SKU</span>
+    <span class="product-price" data-needs="NEEDS_PRICE">NEEDS_PRICE</span>
+  </a>
+  <a href="#" data-needs="NEEDS_PRODUCT_NAME" class="product-card">
+    <span data-needs="NEEDS_PRODUCT_IMAGE" class="product-thumb">NEEDS_PRODUCT_IMAGE</span>
+    <span class="product-name">NEEDS_PRODUCT_NAME</span>
+    <span class="product-sku" data-needs="NEEDS_SKU">NEEDS_SKU</span>
+    <span class="product-price" data-needs="NEEDS_PRICE">NEEDS_PRICE</span>
+  </a>
+  <a href="#" data-needs="NEEDS_PRODUCT_NAME" class="product-card">
+    <span data-needs="NEEDS_PRODUCT_IMAGE" class="product-thumb">NEEDS_PRODUCT_IMAGE</span>
+    <span class="product-name">NEEDS_PRODUCT_NAME</span>
+    <span class="product-sku" data-needs="NEEDS_SKU">NEEDS_SKU</span>
+    <span class="product-price" data-needs="NEEDS_PRICE">NEEDS_PRICE</span>
+  </a>
+  <a href="#" data-needs="NEEDS_PRODUCT_NAME" class="product-card">
+    <span data-needs="NEEDS_PRODUCT_IMAGE" class="product-thumb">NEEDS_PRODUCT_IMAGE</span>
+    <span class="product-name">NEEDS_PRODUCT_NAME</span>
+    <span class="product-sku" data-needs="NEEDS_SKU">NEEDS_SKU</span>
+    <span class="product-price" data-needs="NEEDS_PRICE">NEEDS_PRICE</span>
+  </a>
+</div>
+```
+
+Brand logo in a header — single occurrence, density rule does NOT apply (section.interactive_data_slots empty — static slot):
+```
+<a href="/" class="logo">
+  <span data-needs="NEEDS_BRAND_NAME">NEEDS_BRAND_NAME</span>
+</a>
+```
+
+Order row in order-history — pattern shape shown once; renderer applies BK-231 density to emit 4 such rows (section.interactive_data_slots contains NEEDS_ORDER_ID, NEEDS_DATE, NEEDS_TOTAL):
+```
+<a href="#" data-needs="NEEDS_ORDER_ID" class="order-row">
+  <span class="order-id">NEEDS_ORDER_ID</span>
+  <span class="order-date" data-needs="NEEDS_DATE">NEEDS_DATE</span>
+  <span class="order-total" data-needs="NEEDS_TOTAL">NEEDS_TOTAL</span>
+</a>
+```
+
+## Factual content from project-facts (BK-229)
+
+Before emitting any NEEDS_* marker, check `tokens.brand` in `DESIGN_TOKENS.json` for a matching factual value. If the field is non-null and non-empty, render the value as visible text and OMIT the `data-needs` attribute and `NEEDS_*` marker. If the field is null or empty, fall back to the BK-227 wrapper emit rule.
+
+Marker → token field mapping:
+
+| NEEDS_* marker | tokens.brand field |
+|---|---|
+| NEEDS_BRAND_NAME | brand.name |
+| NEEDS_COMPANY_NAME | brand.company |
+| NEEDS_CONTACT_URL | brand.contactUrl |
+| NEEDS_PRIVACY_URL | brand.privacyUrl |
+| NEEDS_TERMS_URL | brand.termsUrl |
+| NEEDS_CATEGORY_LABEL | brand.categories[i].label (keyed by element's `data-key` attribute) |
+
+For NEEDS_CATEGORY_LABEL specifically — when a slot is also classified interactive (BK-227), the result combines both rules:
+- BK-227 wraps as `<a href="#" data-needs="NEEDS_CATEGORY_LABEL" data-key="cable">`
+- BK-229 fills label from `brand.categories` if `{ key: "cable", label: "..." }` present
+- Combined output: `<a href="#" data-key="cable">...label...</a>`
+
+### Examples (BK-229)
+
+Header brand (BK-227 static + BK-229 fact):
+- `tokens.brand.name = "Esteam"`: `<a href="/" class="logo">Esteam</a>`
+- `tokens.brand.name = null`: `<a href="/" class="logo"><span data-needs="NEEDS_BRAND_NAME">NEEDS_BRAND_NAME</span></a>`
+
+Footer contact URL (BK-227 static + BK-229 fact):
+- `tokens.brand.contactUrl = "https://example.com/contact"`: `<a href="https://example.com/contact">Contact</a>`
+- null: `<a href="#" data-needs="NEEDS_CONTACT_URL">Contact</a>`
+
+Category nav (BK-227 interactive + BK-229 fact, keyed by `data-key`):
+- `tokens.brand.categories[0] = { key: "cable", label: "Cable" }`: `<a href="#" data-key="cable">Cable</a>`
+- absent: `<a href="#" data-needs="NEEDS_CATEGORY_LABEL" data-key="cable">NEEDS_CATEGORY_LABEL</a>`
+
+Boundary: do NOT derive `name`, `company`, `*Url`, or `categories` from requirement text, screen names, or any other source. The only source of factual content is the `tokens.brand` block populated by `--project-facts`.
+
+## Inter-screen navigation (BK-232)
+
+The MVP prototype is a click-through demo across 10 sibling HTML files in `docs/design/prototype/screens/`. When emitting `<a>` elements for top-nav, footer-nav, or sidebar-nav links, convert SPEC-declared route paths to file-relative paths so clicking in browser navigates to the correct sibling file.
+
+### Canonical route → file mapping
+
+| Route prefix (from brief / SPEC) | Target `href` value |
+|---|---|
+| `/` | `home.html` |
+| `/category` or `/category/*` | `category.html` |
+| `/product` or `/product/*` | `product-detail.html` |
+| `/search` | `search.html` |
+| `/cart` | `cart.html` |
+| `/checkout` or `/checkout/*` | `checkout.html` |
+| `/account` or `/account/info` | `account-info.html` |
+| `/account/orders` (exact) | `order-history.html` |
+| `/account/orders/*` (any order id) | `order-detail.html` |
+| `/configure` or `/configure/*` | `mode-b-configurator.html` |
+
+### Fallback rule
+
+Routes NOT in the mapping (`/account/quotes`, `/account/addresses`, `/logout`, `/shipping`, `/faq`, `/about`, `/help`, `/admin`, `/api/*`, etc.) → emit `href="#"` (BK-227 skeleton anchor). The placeholder is honest: no rendered file exists for the route.
+
+### Factual URL priority (BK-229)
+
+When `tokens.brand.contactUrl` / `privacyUrl` / `termsUrl` is non-null AND the link is a footer contact / privacy / terms link, use the supplied URL directly as `href` (overrides the mapping; BK-229 facts always take priority over routing).
+
+### Current-page marker
+
+When the rendered file IS the current screen (e.g. `order-history.html` rendering the `/account/orders` route), mark the matching nav link with `aria-current="page"`. Keep the `href` value pointing to the same file (self-link is fine).
+
+### Example
+
+In `home.html` top nav:
+```
+<nav aria-label="Main navigation">
+  <a href="category.html">高圧ケーブル</a>
+  <a href="category.html">開閉器（PAS）</a>
+  <a href="category.html">金具・支持材</a>
+  <a href="category.html">碍子・絶縁材</a>
+  <a href="search.html">検索</a>
+  <a href="mode-b-configurator.html">Mode B</a>
+  <a href="account-info.html" class="btn btn-secondary">アカウント</a>
+  <a href="cart.html" class="btn btn-primary">カート</a>
+</nav>
+```
+
+In `order-history.html` sidebar (current page = order-history):
+```
+<nav class="account-nav" aria-label="アカウントナビゲーション">
+  <h2>マイアカウント</h2>
+  <ul>
+    <li><a href="account-info.html">ダッシュボード</a></li>
+    <li><a href="order-history.html" aria-current="page">注文履歴</a></li>
+    <li><a href="#">見積一覧</a></li>
+    <li><a href="account-info.html">アカウント情報</a></li>
+    <li><a href="#">配送先一覧</a></li>
+    <li><a href="#">ログアウト</a></li>
+  </ul>
+</nav>
+```
+
+## CSS scope checklist for nav elements (BK-233)
+
+When a screen contains multiple `<nav>` elements (e.g. header nav + sidebar account nav + footer nav), generic `nav ul { ... }` rules cascade into ALL nav contexts and break nested layouts. The renderer MUST scope every nav-targeting CSS rule to its structural context.
+
+### Required scoping per nav context
+
+1. **Header nav** — use `header nav ul { display: flex; ... }` (NEVER bare `nav ul`).
+2. **Sidebar nav / account nav / side panel nav** — explicit `display: block` (or `flex-direction: column`) on the scoped class selector. Example: `.account-nav ul { display: block; }`.
+3. **Footer nav** — same discipline: `footer nav ul { display: flex; ... }` if horizontal, OR explicit `display: block` if vertical.
+
+Rule: if a `<nav>` element appears in more than one structural context within the same screen, scope EVERY nav-targeting rule with a parent selector. Never rely on cascade defaults for nested nav.
+
+### Negative example (DON'T)
+
+```
+/* Generic nav ul cascades into ALL nav children — breaks sidebar */
+nav ul { list-style: none; display: flex; gap: 1.5rem; }
+.account-nav ul { list-style: none; }  /* missing display reset! cascade wins */
+```
+
+Result: sidebar `<li>` items render in a horizontal row, each becoming a narrow column where Japanese/CJK characters wrap one-per-line.
+
+### Positive example (DO)
+
+```
+/* Scope header explicitly */
+header nav ul { list-style: none; display: flex; gap: 1.5rem; }
+header nav li { margin: 0; }
+
+/* Sidebar explicitly declares display: block */
+.account-nav ul { list-style: none; display: block; margin: 0; padding: 0; }
+.account-nav li { display: block; margin-bottom: 0.25rem; }
+.account-nav a { display: block; padding: 0.5rem 0.75rem; }
+```
+
+Result: header nav horizontal, sidebar nav proper vertical menu list.
+
+### Sanity check during rendering
+
+For each screen with multiple `<nav>` elements, verify before output:
+- Does every `nav`-targeting rule have a parent selector (`header nav`, `footer nav`) OR a class scope (`.account-nav`)?
+- Do nested nav class rules explicitly set `display`?
+- Are there any bare `nav ul` or `nav li` rules without a parent / class scope?
+
+If any check fails, fix the CSS before emitting the HTML file.
+
+## Boundaries
+
+- Brand, palette, typography, spacing, mood, and component direction come only from `docs/design/DESIGN_SYSTEM.md` and `docs/design/DESIGN_TOKENS.json`.
+- Do not infer brand direction from requirements, source quotes, screen names, or sample file names.
+- Do not read `docs/ui/**` before generation completes.
+- Do not copy or hash-match sample HTML, PNG, or other reference files.
+- Do not hardcode Esteam screen names, routes, palette, copy, or layouts.
+- Do not call a network service, start a daemon, spawn a subprocess, or require an API key.
+- Do not create `.sdtk/atlas`.

package/skills/design-prototype/references/craft.md

@@ -0,0 +1,75 @@
+# Prototype Craft Rules
+
+These rules sit on top of `docs/design/DESIGN_SYSTEM.md` and `docs/design/DESIGN_TOKENS.json`. If there is a conflict, project design tokens and the design system define the brand; these rules define execution quality.
+
+## Anti-Slop
+
+Must-fix patterns:
+
+- Default Tailwind indigo or purple hex values used directly.
+- Two-stop trust gradients on hero sections.
+- Emoji inside headings, buttons, feature icons, or primary navigation.
+- Rounded cards with colored left-border accents.
+- Invented metrics such as "10x faster" or "99.9% uptime".
+- Filler copy such as lorem ipsum, sample content, placeholder text, or numbered product cards.
+- Repeated article/card bodies that only change the heading.
+
+Should-fix patterns:
+
+- Generic hero, feature, pricing, FAQ, CTA sequence when the screen brief calls for an app surface.
+- Placeholder image CDNs.
+- More than 12 raw hex values outside `:root`.
+- `var(--accent)` or `var(--primary)` used so often that everything competes for attention.
+- Decorative blob or wave SVG backgrounds.
+
+## Color
+
+- Plan four layers before writing CSS: neutrals, one accent, semantic colors, and rare effects.
+- Use tokens or CSS custom properties. Avoid raw hex outside `:root`.
+- Keep accent use scarce: usually one primary CTA and one secondary signal per screen.
+- Do not introduce a second accent unless `DESIGN_TOKENS.json` declares it.
+- Normal text must meet WCAG AA contrast: 4.5:1 for body, 3:1 for large text and UI components.
+- Avoid pure black and pure white backgrounds; use tokenized near-black/near-white values when available.
+
+## Typography
+
+- Use the font families and scale from the design system.
+- Cap visible type levels to a small, intentional set.
+- One element should be the dominant entry point in each visual region.
+- Use at least two hierarchy vectors for the dominant element: scale, weight, spacing, tracking, or alignment.
+- Body copy should stay readable, with a comfortable line length around 50-75 characters.
+- Button and label text should be concrete and action-oriented.
+- All-caps labels need positive tracking; display sizes need deliberate tighter tracking.
+
+## Layout And Composition
+
+- Prefer product-specific structure over generic cards.
+- Use CSS Grid for real layout relationships, not only equal card rows.
+- Vary density by screen purpose: dashboards and tables may be tight; landing and decision areas need more air.
+- Do not place cards inside larger decorative cards.
+- Keep navigation and repeated controls stable across screens.
+- Use one decisive flourish: a proportion, type treatment, state surface, or interaction detail that supports the brief.
+
+## State Coverage
+
+Every interactive list, table, card, form, search, or workflow surface needs visible handling for:
+
+- Loading
+- Empty
+- Error
+- Populated
+- Edge cases such as long text, missing optional fields, large result counts, or disabled actions
+
+Empty states need a headline, plain explanation, and action. Error states need what happened, why if knowable, and what the user can do next.
+
+## Accessibility Baseline
+
+- One `<h1>` per document.
+- Use semantic landmarks: `<header>`, `<nav>`, `<main>`, `<section>`, `<aside>`, `<footer>`.
+- Prefer native controls over ARIA recreations.
+- Inputs have visible labels.
+- Icon-only controls have accessible names.
+- Keyboard focus is visible with `:focus-visible`.
+- Interactive targets should be at least 44px when practical.
+- Do not rely on color alone for status.
+- Respect reduced-motion preferences for animation.

package/skills/design-prototype/references/designer-charter.md

@@ -0,0 +1,56 @@
+# Designer Charter
+
+You are an expert designer working in HTML. Your job is to produce thoughtful, well-crafted, engineered prototype screens as standalone HTML documents.
+
+## Operating Model
+
+Work inside the project filesystem. The manifest tells you which files to write. Write files directly to the manifest `outPath`; do not hand off HTML through chat-only wrappers.
+
+## Workflow
+
+1. Understand the requested output, fidelity, constraints, screen purpose, audience, and active design system.
+2. Explore provided resources before building. Read the manifest, design system, tokens, craft reference, and the current screen brief.
+3. Plan the visual system before writing: background, type scale, layout pattern, density, interaction states, and one decisive flourish.
+4. Build the HTML file. Show real structure early in the file: landmarks, clear heading, primary action, state surfaces, and content tied to the brief.
+5. Verify the completed file before moving to the next screen.
+
+## HTML Output Rules
+
+- The HTML must be complete and standalone.
+- Inline all CSS in the document.
+- Use semantic landmarks and native controls first.
+- Keep each file under roughly 1000 lines.
+- Use modern CSS deliberately: Grid, container queries where useful, `color-mix()`, `text-wrap: pretty`, and custom properties.
+
+## Content Rules
+
+- No filler copy, dummy sections, placeholder text, or invented metrics.
+- Use real content from the screen brief: purpose, data slots, user intent, primary action, component expectations, states, and acceptance criteria.
+- Ask for clarification only when a required product fact is impossible to infer from the manifest, design system, tokens, and brief.
+- Use sentence-case headings by default.
+- Mobile hit targets are at least 44px when practical.
+- Do not surprise-add flows or sections outside the brief.
+
+## Anti-AI-Slop Rules
+
+Avoid these patterns:
+
+- Aggressive gradient backgrounds.
+- Gratuitous emoji.
+- Rounded boxes with a colored left-border accent.
+- SVG-as-illustration when a neutral placeholder or real content block belongs there.
+- Overused fonts used without justification.
+- Generic warm beige, peach, pink, orange, or brown canvas treatments when not brand-led.
+- Default indigo or purple accents unless the design tokens explicitly require them.
+- Decorative blobs, bokeh, or wave backgrounds without a functional role.
+
+## Visual Craft
+
+Use restraint plus one decisive flourish. The page should feel specific to the product through structure, copy, state design, and proportions, not through decoration.
+
+## What Not To Do
+
+- Do not recreate copyrighted designs or another company's distinctive UI.
+- Do not mention tool internals in the generated HTML.
+- Do not include raw source JSON or debug panels.
+- Do not use product-specific sample files as a generation source.