@systemverification/styling-kit 2.0.0

package/CLAUDE.md

@@ -0,0 +1,98 @@
+# Claude Styling Instructions – System Verification
+
+# System Verification — Styling Kit
+
+This repo is the **canonical source** for the System Verification design system and brand assets. It is not an application — it is a portable kit that gets copied into new projects.
+
+## Purpose
+
+Provides consistent System Verification branding for new projects bootstrapped with Claude:
+
+- `docs/DESIGN_SYSTEM.md` — **single source of truth** for all visual decisions: brand colors, typography, component specs (Button, Card, Badges, Inputs, Toasts), layout conventions, animations, and common anti-patterns
+- `docs/COMPONENTS/` — per-component specs extracted from DESIGN_SYSTEM.md
+- `docs/BAD_EXAMPLES.md` — anti-pattern reference
+- `tokens/tokens.css` — CSS custom properties (source of truth for the token file)
+- `README.md` — instructions for consuming this kit in a new project, including ready-made Claude prompts
+- `assets/` — static brand assets installed into target projects by the CLI
+- `bin/sv-style.js` — CLI entry point (`init`, `update`, `mcp`)
+- `src/` — CLI and MCP server implementation (Node.js ESM)
+
+## Asset Inventory
+
+```
+assets/
+├── favicon.png              # "S" symbol, orange/gold, ~92 KB
+├── logo/logo.svg            # "System Verification" wordmark, white SVG (dark backgrounds only)
+└── fonts/
+    ├── body-font.woff2      # BodyFont regular
+    ├── body-font-italic.woff2
+    └── heading-font.woff2   # HeadingFont
+```
+
+## Design System
+
+Follow `docs/DESIGN_SYSTEM.md` for all visual decisions. Key constraints:
+
+- **Never hardcode brand colors** — always use the `var(--color-*)` tokens
+- **Dark mode only** — no light theme is defined
+- **Yellow (`#F7F965`) is the only accent color** — do not introduce additional accent hues
+- **Logo is white SVG** — only suitable for dark backgrounds
+- **Fonts are self-hosted** — no external CDN dependencies
+
+## Modifying This Kit
+
+When updating this kit, keep changes consistent:
+
+1. **`docs/DESIGN_SYSTEM.md`** — update token values, component patterns, visual rules, or anti-patterns
+2. **`docs/COMPONENTS/`** — update component-specific spec files to match DESIGN_SYSTEM.md
+3. **`docs/BAD_EXAMPLES.md`** — update anti-patterns section to match DESIGN_SYSTEM.md
+4. **`tokens/tokens.css`** — update CSS custom properties when token values change
+5. **`README.md`** — update the ready-made prompts and brand quick reference table if tokens change
+6. **`assets/`** — update binary assets (fonts, logo, favicon) when the brand is refreshed
+7. **`src/mcp.js`** — update `PALETTE_TUPLES` when palette values change
+
+The CLI (`bin/sv-style.js`, `src/`) and MCP server (`src/mcp.js`) are core parts of this kit. Keep them working when updating the kit.
+
+Do not add framework-specific application logic. The kit must remain stack-agnostic.
+
+
+---
+
+# Additional Enforcement Rules
+
+## 1. Token Enforcement
+
+If a value exists in docs/DESIGN_SYSTEM.md:
+→ MUST use it
+→ MUST NOT recreate it
+
+## 2. No Visual Guessing
+
+If something is not defined:
+- reuse closest existing pattern
+- do not invent new style language
+
+## 3. Component Consistency
+
+If a Button, Card, Badge, Input, or Toast is generated:
+→ it must match `docs/DESIGN_SYSTEM.md` exactly in structure, tokens, required states
+→ do not add variants, rename tokens, or omit required states
+
+## 4. Density Awareness
+
+Default to **product UI density**, not marketing spacing.
+
+## 5. Output Quality
+
+Code must:
+- be production-ready
+- not contain magic numbers
+- not depend on hidden context
+
+## 6. Anti-Pattern Enforcement
+
+Before generating any styled code, consult `docs/BAD_EXAMPLES.md` and the "Common Styling Anti-Patterns" section in `docs/DESIGN_SYSTEM.md`:
+→ hardcoded colors are forbidden — always use `var(--color-*)` tokens
+→ magic spacing values are forbidden — always use consistent spacing values
+→ accent color (`--color-yellow`) must only be used for interactive/CTA elements
+→ all interactive components must include hover, focus-visible, active, and disabled states

package/README.md

@@ -0,0 +1,411 @@
+# System Verification — Styling Kit
+
+A portable design system for bootstrapping new System Verification projects with consistent branding using Claude.
+
+---
+
+## What's Included
+
+```
+styling-kit/
+├── bin/sv-style.js           # CLI entry point
+├── src/
+│   ├── init.js               # init command
+│   ├── update.js             # update command
+│   └── mcp.js                # MCP validation server
+├── tokens/tokens.css         # CSS custom properties (source)
+├── assets/
+│   ├── favicon.png           # "S" symbol — orange/gold
+│   ├── logo/logo.svg         # Wordmark — white SVG
+│   └── fonts/
+│       ├── body-font.woff2
+│       ├── body-font-italic.woff2
+│       └── heading-font.woff2
+├── docs/
+│   ├── DESIGN_SYSTEM.md      # Single source of truth
+│   ├── COMPONENTS/
+│   │   ├── BUTTON.md
+│   │   └── CARD.md
+│   └── BAD_EXAMPLES.md
+└── templates/
+    └── CLAUDE_SNIPPET.md     # Appended to target project CLAUDE.md
+```
+
+---
+
+## Setup in a New Project
+
+### 1. Install with the CLI
+
+Run from the **root of your target project**:
+
+```bash
+node /path/to/styling-kit/bin/sv-style.js init
+```
+
+This will:
+- Copy `tokens/tokens.css` → `src/styles/sv/tokens.css`
+- Copy `assets/` → `public/sv-assets/`
+- Copy `docs/` → `docs/sv-style/`
+- Generate `sv-style.json` recording the installed paths
+- Patch (or create) `CLAUDE.md` with an SV Style reference block
+
+**Custom paths:**
+
+```bash
+node /path/to/styling-kit/bin/sv-style.js init \
+  --styles-dir src/styles/sv \
+  --assets-dir public/sv-assets \
+  --docs-dir docs/sv-style
+```
+
+### 2. Keep in sync
+
+When the kit is updated, run from your project root:
+
+```bash
+node /path/to/styling-kit/bin/sv-style.js update
+```
+
+Reads paths from `sv-style.json` and overwrites all managed files.
+
+---
+
+## MCP Validation Server
+
+The kit includes an MCP server for Claude to validate styling in your project.
+
+### Start the server
+
+```bash
+node /path/to/styling-kit/bin/sv-style.js mcp
+```
+
+### Client configuration
+
+**Claude Desktop** — `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+  "mcpServers": {
+    "sv-style": {
+      "command": "node",
+      "args": ["C:/path/to/styling-kit/bin/sv-style.js", "mcp"],
+      "cwd": "C:/your-target-project"
+    }
+  }
+}
+```
+
+`cwd` sets the working directory for `validate_file` path resolution and `sv-style.json` lookup. Set it to your target project root.
+
+**Claude Code** — `.claude/settings.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "sv-style": {
+      "command": "node",
+      "args": ["C:/path/to/styling-kit/bin/sv-style.js", "mcp"]
+    }
+  }
+}
+```
+
+Claude Code uses the workspace root as `cwd` automatically.
+
+**VS Code** — `.vscode/mcp.json` in your project root:
+
+```json
+{
+  "servers": {
+    "sv-style": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["C:/path/to/styling-kit/bin/sv-style.js", "mcp"]
+    }
+  }
+}
+```
+
+Note the different key (`"servers"` not `"mcpServers"`) and the required `"type": "stdio"` field.
+
+**VS Code — tool discovery:** VS Code proxies all `.vscode/mcp.json` servers through a `vscode-mcp-gateway` layer, so tools appear as `mcp__vscode-mcp-gateway__<tool_name>` regardless of server name. Keyword search in ToolSearch does not index them through this gateway — use the exact `select:` syntax:
+
+```
+select:mcp__vscode-mcp-gateway__validate_file
+select:mcp__vscode-mcp-gateway__get_tokens
+select:mcp__vscode-mcp-gateway__get_component_spec
+```
+
+In Claude Code (`.claude/settings.json`), the server is registered directly under the `"sv-style"` key, so the prefix is `mcp__sv-style__`.
+
+### Available MCP tools
+
+| Tool | Description |
+|---|---|
+| `get_tokens()` | Returns the full CSS token definitions |
+| `get_component_spec({ name })` | Returns the component spec markdown (e.g. `BUTTON`, `CARD`) |
+| `validate_file({ path })` | Validates a CSS/HTML file for design system violations |
+
+### Validation rules
+
+- **Hardcoded hex colors** — any `#rrggbb` value in a CSS property (should use `var(--color-*)`)
+- **Hardcoded px font sizes** — `font-size` set in `px` (should use `rem` scale)
+- **Non-palette rgba values** — `rgba()` using RGB numbers not from the documented palette
+
+### Validation output format
+
+```json
+[
+  {
+    "type": "error",
+    "rule": "no-hardcoded-hex",
+    "message": "Hardcoded hex color: #123456 — use a var(--color-*) token instead",
+    "line": 14
+  }
+]
+```
+
+An empty array means no violations found.
+
+---
+
+## Styling an Existing App with AI
+
+End-to-end workflow for applying SV branding to a web app using an AI coding assistant
+(Claude Code, VS Code Copilot with Claude, or similar).
+
+### Step 1 — Clone the kit (one-time)
+
+The CLI and MCP server run directly from a local clone — no npm publish required.
+
+```bash
+git clone <this-repo-url> C:/tools/styling-kit
+cd C:/tools/styling-kit
+npm install
+```
+
+### Step 2 — Run init in your target project
+
+From the root of your project:
+
+```bash
+node C:/tools/styling-kit/bin/sv-style.js init
+```
+
+This installs tokens, assets, and docs and patches `CLAUDE.md`. See
+[Setup in a New Project](#setup-in-a-new-project) for path options.
+
+After running, your project will contain:
+- `sv-style.json` — records installed paths
+- `AGENTS.md` — design system context and workflow for any AI agent
+- `CLAUDE.md` — Claude-specific MCP tool discovery (references AGENTS.md)
+- `docs/sv-style/DESIGN_SYSTEM.md` — managed copy of the visual spec
+- `src/styles/sv/tokens.css` (or your custom `--styles-dir`) — CSS custom properties
+
+### Step 3 — Add MCP config to your project
+
+Add the MCP server so your AI assistant can validate CSS and fetch component specs.
+
+**VS Code (Copilot with Claude, agent mode)** — `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "sv-style": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["C:/tools/styling-kit/bin/sv-style.js", "mcp"]
+    }
+  }
+}
+```
+
+**Claude Code** — `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "sv-style": {
+      "command": "node",
+      "args": ["C:/tools/styling-kit/bin/sv-style.js", "mcp"]
+    }
+  }
+}
+```
+
+See [MCP Validation Server](#mcp-validation-server) for all client options and available tools.
+
+### Step 4 — Paste the styling prompt
+
+Open an AI chat in your project workspace and paste the prompt below. The AI will read
+the design system, apply consistent branding across your components, validate the output,
+and fix any violations automatically.
+
+### Agent prompt — style this app
+
+Copy and paste this into your AI coding assistant after completing steps 1–3:
+
+```
+Style this app using the installed System Verification design system.
+
+Context:
+- sv-style.json, AGENTS.md, CLAUDE.md, docs/sv-style/, and the tokens CSS are already in this project
+- Use AGENTS.md and docs/sv-style/DESIGN_SYSTEM.md as the source of truth for all decisions
+- Use MCP tools if available. Load them first with ToolSearch select: syntax:
+  - VS Code: `select:mcp__vscode-mcp-gateway__get_tokens` / `get_component_spec` / `validate_file`
+  - Claude Code: `select:mcp__sv-style__get_tokens` / `get_component_spec` / `validate_file`
+
+Before writing any CSS:
+1. Load and call get_tokens, read the full output
+2. Read docs/sv-style/DESIGN_SYSTEM.md
+3. For each interactive component (button, input, card), call get_component_spec to check
+   whether a spec exists — only style to spec if one is found; otherwise follow the design
+   system conventions directly
+
+Adding styles:
+4. Identify the app entry point and main layout/component files
+5. Import tokens.css before all other stylesheets in the entry point
+6. Create a single app-level CSS file (e.g. app.css) for all layout and component styles
+7. Add flat BEM-like class names to component markup — do not change behaviour or logic
+   Use names like: app-shell, app-header, app-brand, app-layout, app-sidebar, app-main,
+   app-footer, form-field, form-label, form-input, form-error, button-primary,
+   button-secondary, is-current, is-done, empty-state, content-block
+8. Style all interactive controls used in the app:
+   - text inputs and textareas
+   - select dropdowns
+   - radio buttons and checkboxes
+   - buttons (primary, secondary, danger)
+   - pre / code blocks
+9. Implement the standard app layout:
+   - full-height shell
+   - sticky header
+   - sidebar + main two-column layout on desktop
+   - single column at ≤900px
+   - footer anchored at bottom
+
+Visual design requirements:
+- Dark background using var(--color-dark-blue)
+- Headings in HeadingFont, body text in BodyFont
+- Sidebar: highlight current/active item with yellow treatment; mark completed items visibly
+- Cards and panels: use documented translucent surfaces and borders
+- Technical content blocks (code, output, pre): distinct styled areas
+- Buttons: all five states — default, hover, active, focus-visible, disabled
+- Inputs and selects: visible focus-visible yellow outline
+- Error text: use error tokens/palette
+- Muted/placeholder text: use documented muted palette values
+
+Hard constraints:
+- Do not hardcode colors — always use var(--color-*) tokens
+- Do not use px for font-size — use rem
+- Use only tokens and documented palette values for rgba()
+- Dark mode only — no light theme
+- Yellow (--color-yellow) is the only accent — use only on interactive/CTA elements
+- Self-hosted fonts ("BodyFont", "HeadingFont") are already installed — add no external refs
+- Do not change behaviour, flow logic, or existing content — only add classes and styles
+
+After editing:
+- Call validate_file on each CSS file you created or modified
+- Fix all violations until every result is an empty array
+- Provide: a short summary of changed files, the final validate_file result, and any
+  remaining assumptions or known limitations
+```
+
+---
+
+## Ready-Made Claude Prompts
+
+### Full scaffold — base CSS + HTML + layout shell
+
+```
+Read docs/sv-style/DESIGN_SYSTEM.md and src/styles/sv/tokens.css in this project,
+then do the following:
+
+1. Create a base CSS file that includes:
+   - @import or inline the tokens from src/styles/sv/tokens.css
+   - CSS reset (* { box-sizing: border-box; margin: 0; padding: 0; })
+   - Base body styles: BodyFont, dark-blue background, sand text, antialiased
+   - Base heading styles: HeadingFont, white, weight 600
+   - Sticky header with frosted-glass effect (backdrop-filter blur, dark-blue bg,
+     light-blue border-bottom)
+   - Button variants: .btn-primary, .btn-secondary, .btn-danger (pill radius)
+   - Badge variants: .badge with .badge-success, .badge-error, .badge-warning
+   - Input and select base styles (dark-blue bg, sand border, yellow focus ring)
+   - Card component (.card — translucent bg, hover lift)
+   - Toast component (.toast — pill radius, floating shadow)
+
+2. Set up the HTML head with charset, viewport, favicon, title, and CSS link.
+
+3. Create a base layout: sticky header (logo at 28px + project title),
+   <main> at max-width 1300px centered with 2rem/2.5rem padding, minimal footer.
+
+Keep it minimal — only what DESIGN_SYSTEM.md specifies.
+```
+
+### Minimal — CSS tokens only
+
+```
+Read docs/sv-style/DESIGN_SYSTEM.md and create only a base CSS file with the
+@font-face declarations, :root tokens, CSS reset, and body/heading base styles.
+Do not create any HTML or layout components.
+```
+
+### Tailwind — generate config from tokens
+
+```
+Read docs/sv-style/DESIGN_SYSTEM.md and create a tailwind.config.js that extends
+the default theme with:
+- colors: dark-blue, light-blue, sand, yellow, white, error, success
+- borderRadius: sm (4px), md (8px), pill (100px)
+- fontFamily: body (BodyFont, sans-serif), heading (HeadingFont, sans-serif)
+- transitionDuration and timingFunction matching var(--transition)
+
+Add @font-face declarations to the global CSS layer. Use exact values from
+DESIGN_SYSTEM.md — do not approximate or rename tokens.
+```
+
+### React — scaffold component library with CSS modules
+
+```
+Read docs/sv-style/DESIGN_SYSTEM.md and create a set of React components:
+- Button (variants: primary, secondary, danger)
+- Badge (variants: success, error, warning, info)
+- Card (with hover lift)
+- Input (yellow focus ring)
+- AppHeader (sticky, frosted glass, logo + title)
+- Toast (floating, default + error)
+
+Use CSS modules (*.module.css). Import tokens from src/styles/sv/tokens.css.
+Follow exact values from DESIGN_SYSTEM.md.
+```
+
+---
+
+## Brand Quick Reference
+
+| Element | Value |
+|---|---|
+| Primary background | `var(--color-dark-blue)` — `#0B1B28` |
+| Secondary background | `var(--color-light-blue)` — `#435364` |
+| Primary text | `var(--color-sand)` — `#F2F2EA` |
+| Accent / CTA | `var(--color-yellow)` — `#F7F965` |
+| Headings | `var(--color-white)` — `#ffffff` |
+| Error | `var(--color-error)` — `#ef4444` |
+| Success | `var(--color-success)` — `#10b981` |
+| Body font | `"BodyFont", sans-serif` |
+| Heading font | `"HeadingFont", sans-serif` |
+| Border radii | `var(--radius-sm)` 4px · `var(--radius-md)` 8px · `var(--radius-pill)` 100px |
+| Logo | White SVG — dark backgrounds only |
+| Favicon | PNG — orange/gold "S" symbol |
+
+---
+
+## Notes
+
+- **Fonts are self-hosted** `.woff2` files — no external CDN dependencies.
+- **Dark-mode only.** No light theme is defined. If you need one, derive it from existing tokens.
+- **Yellow is the only accent color.** Never introduce additional accent hues.
+- **Logo is white SVG.** Only suitable for dark backgrounds.
+- The CLI is a local Node.js script — no npm publishing required. Run it with `node`.
+- `docs/sv-style/DESIGN_SYSTEM.md` in your project is a **managed copy** — edit the source (`docs/DESIGN_SYSTEM.md` in this kit) and run `update` to propagate changes.

package/bin/sv-style.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { fileURLToPath, pathToFileURL } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 1; i < args.length; i++) {
+    if (!args[i].startsWith('--')) continue;
+    const key = args[i].slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    const next = args[i + 1];
+    if (next && !next.startsWith('--')) {
+      flags[key] = next;
+      i++;
+    } else {
+      flags[key] = true;
+    }
+  }
+  return flags;
+}
+
+switch (command) {
+  case 'init': {
+    const flags = parseFlags(args);
+    const { default: init } = await import(pathToFileURL(join(__dirname, '../src/init.js')));
+    await init(flags);
+    break;
+  }
+  case 'update': {
+    const { default: update } = await import(pathToFileURL(join(__dirname, '../src/update.js')));
+    await update();
+    break;
+  }
+  case 'mcp': {
+    await import(pathToFileURL(join(__dirname, '../src/mcp.js')));
+    break;
+  }
+  case 'login': {
+    const { default: login } = await import(pathToFileURL(join(__dirname, '../src/login.js')));
+    await login();
+    break;
+  }
+  case 'doctor': {
+    const { default: doctor } = await import(pathToFileURL(join(__dirname, '../src/doctor.js')));
+    await doctor();
+    break;
+  }
+  default: {
+    console.log(`SV Style System CLI
+
+Usage:
+  sv-style <command> [options]
+
+Commands:
+  init      Install SV Style into the current project
+  update    Sync SV Style files and refresh private assets
+  login     Check Azure Blob authentication status
+  doctor    Diagnose installation health
+  mcp       Start the MCP validation server (stdio)
+
+Options for init:
+  --styles-dir       <path>   CSS tokens output dir  (default: src/styles/sv)
+  --assets-dir       <path>   Assets output dir       (default: public/sv-assets)
+  --docs-dir         <path>   Docs output dir          (default: docs/sv-style)
+  --public-dir       <path>   Web root directory       (default: public)
+  --require-assets           Fail if private assets cannot be downloaded
+`);
+    if (command) process.exit(1);
+  }
+}