npm package: @systemverification/styling-kit
Description: System Verification design system CLI and MCP validation server
Latest version: 2.2.1

# System Verification — Styling Kit

A portable design system for bootstrapping new System Verification projects with consistent branding using Claude.

**Package:** `@systemverification/styling-kit`
**Version:** 2.0.0

---

## What's Included

The npm package ships the CLI, MCP server, core CSS tokens, docs, and templates.
Brand assets (fonts, logo, favicon) are private and downloaded from Azure Blob at install time.

```
@systemverification/styling-kit (npm)
├── bin/sv-style.js              # CLI entry point
├── src/
│   ├── init.js                  # init command
│   ├── update.js                # update command
│   ├── login.js                 # Azure auth check
│   ├── doctor.js                # installation diagnostics
│   └── mcp.js                   # MCP validation server
├── tokens/tokens-core.css       # CSS custom properties (no @font-face)
├── docs/
│   ├── DESIGN_SYSTEM.md         # Single source of truth
│   ├── COMPONENTS/
│   │   ├── BUTTON.md
│   │   └── CARD.md
│   └── BAD_EXAMPLES.md
└── templates/
    ├── AGENTS_SNIPPET.md        # Appended to target project AGENTS.md
    └── CLAUDE_SNIPPET.md        # Appended to target project CLAUDE.md

Private assets (Azure Blob)
├── fonts/
│   ├── body-font.woff2
│   ├── body-font-italic.woff2
│   └── heading-font.woff2
├── logo/logo.svg                # Wordmark — white SVG
├── favicon.png                  # "S" symbol — orange/gold
└── fonts.css                    # @font-face declarations
```

---

## Installation

### Install the npm package

```bash
npm install @systemverification/styling-kit
```

This gives you the `sv-style` CLI and all public files. No git clone required.

### Run init in your target project

From the **root of your target project**:

```bash
npx sv-style init
```

This will:
- Copy `tokens-core.css` to `src/styles/sv/tokens-core.css`
- Copy `docs/` to `docs/sv-style/`
- Download private brand assets (fonts, logo, favicon) from Azure Blob to `public/sv-assets/`
- Generate `fonts.css` at `src/styles/sv/fonts.css` with correct asset paths
- Write `sv-style.json` recording installed paths and asset version
- Patch (or create) `AGENTS.md` with design system context
- Patch (or create) `CLAUDE.md` with MCP tool discovery instructions

**Custom paths:**

```bash
npx sv-style init \
  --styles-dir src/styles/sv \
  --assets-dir public/sv-assets \
  --docs-dir docs/sv-style \
  --public-dir public
```

**Require assets (fail if download fails):**

```bash
npx sv-style init --require-assets
```

### Degraded mode

If the Azure Blob download fails (not authenticated, network issues, etc.), installation
succeeds in **degraded mode**: system-font fallback declarations are written to `fonts.css`
instead of branded fonts. Everything else (tokens, docs, MCP server) works normally.

To complete the installation later:

```bash
az login
npx sv-style update
```

### Keep in sync

When the kit is updated, run from your project root:

```bash
npx sv-style update
```

Reads paths from `sv-style.json`, overwrites all managed files, and re-downloads the latest
private assets.

---

## CLI Commands

| Command | Description |
|---|---|
| `sv-style init` | Install SV Style into the current project |
| `sv-style update` | Sync files and refresh private assets |
| `sv-style login` | Check Azure Blob authentication status |
| `sv-style doctor` | Diagnose installation health |
| `sv-style mcp` | Start the MCP validation server (stdio) |

All commands can be run via `npx sv-style <command>`.

> **Windows note:** `npx sv-style` may fail to resolve the binary from the scoped package. Use the explicit form instead: `npx --package=@systemverification/styling-kit sv-style <command>`.

---

## Private Assets & Authentication

Brand assets (licensed fonts, logo, favicon) are stored in a private Azure Blob container
and are not included in the npm package.

**Authentication** uses `DefaultAzureCredential` from `@azure/identity`, which reads
credentials from (in order):

1. Environment variables
2. Azure CLI (`az login`)
3. VS Code Azure extension
4. PowerShell (`Connect-AzAccount`)
5. Managed identity (in Azure environments)

The simplest approach for local development:

```bash
az login
npx sv-style init
```

---

## MCP Validation Server

The kit includes an MCP server for Claude to validate styling in your project.

### Start the server

```bash
npx sv-style 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": "npx",
      "args": ["--package=@systemverification/styling-kit", "sv-style", "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": "npx",
      "args": ["--package=@systemverification/styling-kit", "sv-style", "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": "npx",
      "args": ["--package=@systemverification/styling-kit", "sv-style", "mcp"]
    }
  }
}
```

Note the different key (`"servers"` not `"mcpServers"`) and the required `"type": "stdio"` field.

> **Windows alternative:** If `npx` still fails to resolve the binary, use `node` directly:
> ```json
> "command": "node",
> "args": ["node_modules/@systemverification/styling-kit/bin/sv-style.js", "mcp"]
> ```

**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 — Install the package

```bash
npm install @systemverification/styling-kit
```

### Step 2 — Run init in your target project

From the root of your project:

```bash
npx sv-style init
```

This installs tokens, docs, and brand assets and patches `AGENTS.md` and `CLAUDE.md`. See
[Installation](#installation) for path options and authentication.

After running, your project will contain:
- `sv-style.json` — records installed paths and asset version
- `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-core.css` (or your custom `--styles-dir`) — CSS custom properties
- `src/styles/sv/fonts.css` — @font-face declarations (branded or system fallback)

### 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": "npx",
      "args": ["--package=@systemverification/styling-kit", "sv-style", "mcp"]
    }
  }
}
```

**Claude Code** — `.claude/settings.json`:

```json
{
  "mcpServers": {
    "sv-style": {
      "command": "npx",
      "args": ["--package=@systemverification/styling-kit", "sv-style", "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-core.css and fonts.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-core.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-core.css
   - @import src/styles/sv/fonts.css for @font-face declarations
   - 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 that imports
tokens-core.css and fonts.css, adds a CSS reset, and sets 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)

Import tokens-core.css and fonts.css in 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-core.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 licensed and private** — distributed via Azure Blob, not included in the npm package. System font fallbacks are used in degraded mode.
- **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.
- **Node.js >=18 required.**
- `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 `sv-style update` to propagate changes.