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

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:

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:

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):

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:

az login
npx sv-style update

Keep in sync

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

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:

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

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):

{
  "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:

{
  "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:

{
  "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:

"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

[
  {
    "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

npm install @systemverification/styling-kit

Step 2 — Run init in your target project

From the root of your project:

npx sv-style init

This installs tokens, docs, and brand assets and patches AGENTS.md and CLAUDE.md. See 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:

{
  "servers": {
    "sv-style": {
      "type": "stdio",
      "command": "npx",
      "args": ["--package=@systemverification/styling-kit", "sv-style", "mcp"]
    }
  }
}

Claude Code — .claude/settings.json:

{
  "mcpServers": {
    "sv-style": {
      "command": "npx",
      "args": ["--package=@systemverification/styling-kit", "sv-style", "mcp"]
    }
  }
}

See 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.