@systemverification/styling-kit 2.0.0

package/docs/DESIGN_SYSTEM.md

@@ -0,0 +1,614 @@
+# System Verification — Design System
+
+This file defines the visual identity for System Verification products. When building UI, **always follow these conventions** — do not invent new colors, fonts, or spacing values.
+
+---
+
+## Brand Colors (CSS Custom Properties)
+
+Use these as CSS custom properties. Define them in `:root` and reference via `var(--token-name)`.
+
+```css
+:root {
+  /* ── Core palette ── */
+  --color-dark-blue: #0B1B28;    /* Primary background, dark surfaces, input backgrounds */
+  --color-light-blue: #435364;   /* Secondary backgrounds, dividers, card borders */
+  --color-sand: #F2F2EA;         /* Primary text color on dark backgrounds */
+  --color-yellow: #F7F965;       /* Accent / CTA — buttons, links, active states, focus rings */
+  --color-white: #ffffff;        /* Headings text, high-emphasis text */
+
+  /* ── Semantic colors ── */
+  --color-error: #ef4444;        /* Error states, destructive actions, unhealthy badges */
+  --color-success: #10b981;      /* Running/healthy states, positive badges */
+  --color-yellow-hover: #f8faaa; /* Primary button hover — lightened yellow */
+  --color-yellow-active: #f5f950;/* Primary button active — saturated yellow */
+  --color-error-light: #f87171;  /* Danger button text, error badge text — lightened red */
+
+  /* ── Border radius scale ── */
+  --radius-sm: 4px;              /* Inputs, code blocks, small elements */
+  --radius-md: 8px;              /* Cards, form sections, panels */
+  --radius-pill: 100px;          /* Buttons, badges, tags, pills */
+
+  /* ── Motion ── */
+  --transition: 0.3s ease;       /* Default transition for all interactive elements */
+}
+```
+
+### Extended Color Usage
+
+These derivative colors are used throughout the UI. Most are `rgba()` variants of the core palette, used contextually. The tokenized ones (marked with `var(--...)`) **must** be referenced via their token — never hardcoded:
+
+| Purpose | Value | Base color |
+|---|---|---|
+| Card background | `rgba(67, 83, 100, 0.35)` | light-blue |
+| Card/section border | `rgba(67, 83, 100, 0.5)` | light-blue |
+| Header border | `rgba(67, 83, 100, 0.4)` | light-blue |
+| Form label text | `rgba(242, 242, 234, 0.7)` | sand |
+| Secondary/meta text | `rgba(242, 242, 234, 0.5)` | sand |
+| Muted text (placeholders) | `rgba(242, 242, 234, 0.3)` | sand |
+| Subtle borders (inputs) | `rgba(242, 242, 234, 0.15)` | sand |
+| Subtle button hover bg | `rgba(242, 242, 234, 0.1)` | sand |
+| Button hover (yellow) | `var(--color-yellow-hover)` = `#f8faaa` | yellow lightened |
+| Button active (yellow) | `var(--color-yellow-active)` = `#f5f950` | yellow saturated |
+| Yellow badge background | `rgba(247, 249, 101, 0.15)` | yellow |
+| Yellow focus ring shadow | `rgba(247, 249, 101, 0.15)` | yellow |
+| Green badge text | `#34d399` | success lightened |
+| Green badge background | `rgba(16, 185, 129, 0.15)` | success |
+| Red badge text / danger text | `var(--color-error-light)` = `#f87171` | error lightened |
+| Red badge background | `rgba(239, 68, 68, 0.15)` | error |
+| Warning/branch text | `#fb923c` | orange (warning) |
+| Warning background | `rgba(251, 146, 60, 0.1)` | orange |
+
+### Design Principle
+
+The palette is **dark-mode first**. Background is `--color-dark-blue`, primary text is `--color-sand`, headings are `--color-white`, and `--color-yellow` is the singular accent color used for all interactive/CTA elements. Do not introduce additional accent colors.
+
+---
+
+## Typography
+
+### Fonts
+
+Two custom fonts, self-hosted as `.woff2` files:
+
+| Font | CSS family | Usage | File |
+|---|---|---|---|
+| **BodyFont** | `"BodyFont", sans-serif` | All body text (globally inherited) | `fonts/body-font.woff2`, `fonts/body-font-italic.woff2` |
+| **HeadingFont** | `"HeadingFont", sans-serif` | All headings (`h1`–`h6`) | `fonts/heading-font.woff2` |
+| Monospace | `monospace` | Code blocks, technical values | System default |
+
+### @font-face Declarations
+
+```css
+@font-face {
+  font-family: "BodyFont";
+  src: url("/fonts/body-font.woff2") format("woff2");
+  font-weight: normal;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: "BodyFont";
+  src: url("/fonts/body-font-italic.woff2") format("woff2");
+  font-weight: normal;
+  font-style: italic;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: "HeadingFont";
+  src: url("/fonts/heading-font.woff2") format("woff2");
+  font-weight: normal;
+  font-style: normal;
+  font-display: swap;
+}
+```
+
+### Font Weights
+
+| Weight | Usage |
+|---|---|
+| `300` | Body text default |
+| `400` | Meta text, secondary content |
+| `500` | Labels, links, buttons, nav items |
+| `600` | Headings, badges, emphasized labels |
+
+### Font Sizes
+
+| Size | Usage |
+|---|---|
+| `1.05rem` | Card titles |
+| `1rem` | Header title, base size |
+| `0.875rem` | Form inputs |
+| `0.85rem` | Section headings, buttons, toasts |
+| `0.8rem` | Form labels, links, user names |
+| `0.78rem` | Meta text, action buttons, banners |
+| `0.75rem` | Status text, small inputs |
+| `0.7rem` | Status badges, health badges |
+| `0.68rem` | Role badges, code text, small UI |
+| `0.65rem` | Tiny labels |
+
+### Text Styling Conventions
+
+- Headings, labels, badges, and status indicators use `text-transform: uppercase`
+- Letter spacing: `0.02em` for header/CTA text, `0.04em`–`0.05em` for labels and badges
+- Use `-webkit-font-smoothing: antialiased` on `body`
+
+---
+
+## Logo & Favicon
+
+| Asset | File | Format | Notes |
+|---|---|---|---|
+| **Logo** | `logo.svg` | SVG | "System Verification" wordmark in white (`fill: #ffffff`). Display at `height: 28px`. |
+| **Favicon** | `favicon.png` | PNG | "S" symbol in orange/gold tones. ~92 KB. |
+
+### Logo Usage
+
+```html
+<img src="/logo.svg" alt="System Verification" style="height: 28px;">
+```
+
+```html
+<link rel="icon" type="image/png" href="/favicon.png">
+```
+
+The logo SVG uses `fill: #ffffff` — it is designed for dark backgrounds only. If you need it on a light background, you must create a separate dark variant.
+
+---
+
+## Layout Conventions
+
+| Property | Value | Context |
+|---|---|---|
+| Max content width | `1300px` | Header and main content area |
+| Page padding (horizontal) | `2rem` | Header, main |
+| Page padding (vertical) | `2.5rem` top/bottom | Main area |
+| Card grid | `repeat(auto-fill, minmax(340px, 1fr))` | Instance/item cards |
+| Card gap | `1.25rem` | Between grid items |
+| Card padding | `1.5rem` | Inside cards |
+
+### Sticky Header
+
+The header uses a frosted-glass effect:
+
+```css
+header {
+  position: sticky;
+  top: 0;
+  z-index: 100;
+  background: var(--color-dark-blue);
+  backdrop-filter: blur(8px);
+  border-bottom: 1px solid rgba(67, 83, 100, 0.4);
+}
+```
+
+---
+
+## Component Specifications
+
+### Button
+
+**Variants:**
+- **Primary (CTA)**: yellow background for calls-to-action
+- **Secondary/Action**: transparent button for secondary actions
+- **Ghost**: minimal styling for tertiary interactions
+- **Danger**: red-tinted for destructive actions
+
+**Structure:**
+- Button element with rounded pill shape (`border-radius: var(--radius-pill)`)
+- Padding: `0.5rem 1rem` (adjust for density)
+- Font: `0.85rem`, `font-weight: 500`
+- Always uppercase via `text-transform: uppercase`
+
+**Detailed Variants:**
+
+| Variant | Background | Text | Border | Hover State |
+|---|---|---|---|---|
+| Primary | `var(--color-yellow)` | `var(--color-dark-blue)` | none | `var(--color-yellow-hover)` |
+| Secondary | transparent | `var(--color-sand)` | `1px solid rgba(242, 242, 234, 0.2)` | `rgba(242, 242, 234, 0.1)` background |
+| Danger | transparent | `var(--color-error-light)` | `rgba(239, 68, 68, 0.3)` | red-tinted background `rgba(239, 68, 68, 0.1)` |
+
+**Required States** (all buttons must include):
+- **Default**: base styling as defined
+- **Hover**: background/text shift per variant
+- **Active**: darker variant of hover state
+- **Focus-visible**: `outline: 2px solid var(--color-yellow)`, `outline-offset: 2px`
+- **Disabled**: `opacity: 0.5`, `cursor: not-allowed`, no pointer events
+
+**Code Example (Primary):**
+```css
+button.primary {
+  background: var(--color-yellow);
+  color: var(--color-dark-blue);
+  border: none;
+  border-radius: var(--radius-pill);
+  padding: 0.5rem 1rem;
+  font: 0.85rem;
+  font-weight: 500;
+  text-transform: uppercase;
+  cursor: pointer;
+  transition: var(--transition);
+}
+
+button.primary:hover {
+  background: var(--color-yellow-hover);
+}
+
+button.primary:active {
+  background: var(--color-yellow-active);
+}
+
+button.primary:focus-visible {
+  outline: 2px solid var(--color-yellow);
+  outline-offset: 2px;
+}
+
+button.primary:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```
+
+---
+
+### Card
+
+**Structure:**
+- Container with border and translucent background
+- Optional title (uppercase, `1.05rem`, `font-weight: 600`)
+- Content area (flexible layout)
+- Optional footer section
+
+**Styling:**
+- `background: rgba(67, 83, 100, 0.35)`
+- `border: 1px solid rgba(67, 83, 100, 0.5)`
+- `border-radius: var(--radius-md)`
+- `padding: 1.5rem`
+
+**Required States:**
+- **Default**: base styling
+- **Hover**: `transform: translateY(-2px)`, `box-shadow: 0 8px 24px rgba(0, 0, 0, 0.25)`
+- **Focus** (if interactive): highlight border with accent color
+- **Disabled** (if interactive): reduced opacity, no pointer
+
+**Code Example:**
+```css
+.card {
+  background: rgba(67, 83, 100, 0.35);
+  border: 1px solid rgba(67, 83, 100, 0.5);
+  border-radius: var(--radius-md);
+  padding: 1.5rem;
+  transition: var(--transition);
+}
+
+.card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.25);
+}
+
+.card-title {
+  font-family: "HeadingFont", sans-serif;
+  font-size: 1.05rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  color: var(--color-white);
+  margin-bottom: 0.75rem;
+}
+```
+
+---
+
+### Badges / Status Pills
+
+- Pill shaped (`border-radius: var(--radius-pill)`)
+- Font size: `0.68rem`–`0.7rem`, `font-weight: 600`
+- Letter spacing: `0.04em` (uppercase)
+- Background: `0.12`–`0.15` alpha tint of status color
+- Text: lighter shade of status color
+
+**Status Colors:**
+- **Success**: text `#34d399`, background `rgba(16, 185, 129, 0.15)`
+- **Error**: text `#f87171`, background `rgba(239, 68, 68, 0.15)`
+- **Warning**: text `#fb923c`, background `rgba(251, 146, 60, 0.1)`
+- **Yellow/Accent**: text `var(--color-yellow)`, background `rgba(247, 249, 101, 0.15)`
+
+---
+
+### Inputs
+
+- `background: var(--color-dark-blue)`
+- `border: 1px solid rgba(242, 242, 234, 0.15)`
+- `border-radius: var(--radius-sm)`
+- `padding: 0.5rem 0.75rem`
+- `font-size: 0.875rem`
+- `color: var(--color-sand)`
+
+**Required States:**
+- **Default**: as above
+- **Focus**: `border-color: var(--color-yellow)` with `box-shadow: 0 0 0 2px rgba(247, 249, 101, 0.15)`
+- **Disabled**: `opacity: 0.5`, `cursor: not-allowed`
+- **Error**: `border-color: rgba(239, 68, 68, 0.5)`
+
+---
+
+### Toasts / Notifications
+
+- Floating element with `border-radius: var(--radius-pill)`
+- `box-shadow: 0 4px 16px rgba(0, 0, 0, 0.3)`
+- Padding: `1rem 1.5rem`
+
+**Variants:**
+- **Default**: `background: rgba(242, 242, 234, 0.9)`, `color: var(--color-dark-blue)`
+- **Error**: `background: var(--color-error)`, `color: var(--color-white)`
+- **Success**: `background: var(--color-success)`, `color: var(--color-white)`
+
+---
+
+## Common Styling Anti-Patterns
+
+**Before writing any styled code, review these patterns to avoid.**
+
+### ❌ Hardcoded Colors
+
+```css
+/* WRONG */
+background: #123456;
+color: #f0f0f0;
+border-color: #ff9900;
+```
+
+```css
+/* CORRECT */
+background: var(--color-dark-blue);
+color: var(--color-sand);
+border-color: var(--color-yellow);
+```
+
+**Rule:** All colors must use `var(--color-*)` tokens defined in `:root`. Never hardcode hex values.
+
+---
+
+### ❌ Inconsistent or Magic Spacing
+
+```css
+/* WRONG */
+margin: 17px;
+padding: 13px 21px;
+gap: 9px;
+```
+
+```css
+/* CORRECT */
+margin: 1.5rem;  /* Use consistent scale */
+padding: 1rem 1.25rem;
+gap: 0.75rem;
+```
+
+**Rule:** Use the defined spacing scale. No arbitrary pixel values. Use `rem` units for consistency.
+
+---
+
+### ❌ Random Font Sizes (Not on Scale)
+
+```css
+/* WRONG */
+font-size: 15px;
+font-size: 18px;
+font-size: 12px;
+```
+
+```css
+/* CORRECT */
+font-size: 0.875rem;  /* Form inputs */
+font-size: 1rem;      /* Base size */
+font-size: 1.05rem;   /* Card titles */
+```
+
+**Rule:** Use only the defined typography scale. Do not invent new sizes.
+
+---
+
+### ❌ Accent Color Misuse
+
+```css
+/* WRONG */
+background: var(--color-yellow);  /* Large blocks */
+.section { background: var(--color-yellow); }  /* Entire panel */
+```
+
+```css
+/* CORRECT */
+button { background: var(--color-yellow); }  /* CTAs */
+a { color: var(--color-yellow); }  /* Links */
+input:focus { outline-color: var(--color-yellow); }  /* Interactive focus */
+```
+
+**Rule:** Yellow (`--color-yellow`) is **only for interactive/CTA elements**. Never use it for large background areas or non-interactive content.
+
+---
+
+### ❌ Missing Component States
+
+```css
+/* WRONG */
+button {
+  background: var(--color-yellow);
+  color: var(--color-dark-blue);
+}
+/* No hover, focus, active, or disabled states defined */
+```
+
+```css
+/* CORRECT */
+button {
+  background: var(--color-yellow);
+  color: var(--color-dark-blue);
+  transition: var(--transition);
+}
+
+button:hover {
+  background: var(--color-yellow-hover);
+}
+
+button:focus-visible {
+  outline: 2px solid var(--color-yellow);
+}
+
+button:active {
+  background: var(--color-yellow-active);
+}
+
+button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```
+
+**Rule:** All interactive components **must** include `default`, `hover`, `focus-visible`, `active`, and `disabled` states.
+
+---
+
+### ❌ Inline Styles
+
+```css
+/* WRONG */
+<div style="background: red; margin: 10px;">
+```
+
+```css
+/* CORRECT */
+<div class="my-card">
+/* Then in CSS */
+.my-card { background: var(--color-light-blue); margin: 1rem; }
+```
+
+**Rule:** All styles belong in external stylesheets. Never use `style=""` attributes.
+
+---
+
+### ❌ Non-Semantic Color Values
+
+```css
+/* WRONG */
+.label { color: rgba(200, 200, 200, 0.8); }
+```
+
+```css
+/* CORRECT */
+.label { color: rgba(242, 242, 234, 0.7); }  /* Derived from sand token */
+```
+
+**Rule:** All rgba values must be derived from the core palette tokens documented in this spec.
+
+---
+
+## Box Shadows
+
+| Shadow | Usage |
+|---|---|
+| `0 0 0 2px rgba(247, 249, 101, 0.15)` | Input focus ring |
+| `0 8px 24px rgba(0, 0, 0, 0.25)` | Card hover lift |
+| `0 4px 16px rgba(0, 0, 0, 0.3)` | Toast / floating elements |
+
+---
+
+## Animation
+
+| Name | Value | Usage |
+|---|---|---|
+| `pulse-badge` | `opacity 1→0.5→1`, `1.5s ease-in-out infinite` | Loading/starting state badges |
+| Default transition | `0.3s ease` (via `var(--transition)`) | All interactive hover/focus states |
+
+---
+
+## CSS Reset
+
+Always start with this minimal reset:
+
+```css
+* {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+```
+
+---
+
+## Quick Start
+
+To apply this design system to a new project:
+
+1. Copy the `design-system/` folder into your project (see folder structure below)
+2. Add the `@font-face` declarations and `:root` tokens to your main CSS
+3. Reference `logo.svg` and `favicon.png` in your HTML
+4. Use `var(--color-*)` and `var(--radius-*)` tokens — never hardcode brand colors
+5. Follow the typography, component, and layout patterns above
+
+
+---
+
+# Additions (Normalized for AI usage)
+
+## Additional Semantic Tokens
+
+Extend system with these tokens (do NOT remove originals):
+
+```css
+:root {
+  --text-primary: var(--color-white);
+  --text-secondary: rgba(242, 242, 234, 0.7);
+  --text-muted: rgba(242, 242, 234, 0.5);
+
+  --surface-card: rgba(67, 83, 100, 0.35);
+  --surface-hover: rgba(67, 83, 100, 0.5);
+
+  --border-subtle: rgba(67, 83, 100, 0.4);
+  --focus-ring: var(--color-yellow);
+}
+```
+
+## Typography Scale (Explicit)
+
+```css
+--text-display: 48px;
+--text-h1: 32px;
+--text-h2: 24px;
+--text-h3: 18px;
+--text-body: 14px;
+--text-label: 12px;
+```
+
+## Component States (Mandatory)
+
+All components must define:
+
+- default
+- hover
+- active
+- focus-visible
+- disabled
+
+Optional but recommended:
+- loading
+- error
+- success
+
+## Layout Patterns
+
+Derived from systemverification.com:
+
+- Hero (large heading + short intro + CTA)
+- Card grid (3–4 columns desktop)
+- Logo wall (low contrast)
+- Section blocks with clear vertical rhythm
+
+## Key Constraint
+
+This design system is **authoritative**.
+
+AI must:
+- extend it
+- not override it

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@systemverification/styling-kit",
+  "version": "2.0.0",
+  "description": "System Verification design system CLI and MCP validation server",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "sv-style": "bin/sv-style.js"
+  },
+  "scripts": {
+    "test": "node --test src/config.test.js src/bundle.test.js src/assets.test.js src/init.test.js src/update.test.js src/shutdown.test.js src/mcp.test.js",
+    "build:test-bundle": "node scripts/build-test-bundle.js"
+  },
+  "dependencies": {
+    "@azure/identity": "^4.10.0",
+    "@azure/storage-blob": "^12.27.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "adm-zip": "^0.5.16"
+  }
+}

package/src/assets.js

@@ -0,0 +1,67 @@
+import { DefaultAzureCredential } from '@azure/identity';
+import { BlobClient } from '@azure/storage-blob';
+
+const BUNDLE_BLOB_PATH = 'sv-style/assets/latest/asset-bundle.zip';
+
+/**
+ * Download the private asset bundle zip from Azure Blob storage.
+ *
+ * @param {{ accountName: string, containerName: string }} blobConfig
+ * @returns {Promise<Buffer>}
+ * @throws with a `blobErrorType` property identifying the failure category
+ */
+export async function downloadBundle(blobConfig) {
+  const { accountName, containerName } = blobConfig;
+  const url = `https://${accountName}.blob.core.windows.net/${containerName}/${BUNDLE_BLOB_PATH}`;
+
+  const credential = new DefaultAzureCredential();
+  const client = new BlobClient(url, credential);
+
+  let response;
+  try {
+    response = await client.download();
+  } catch (err) {
+    const classified = new Error(userMessage(err));
+    classified.blobErrorType = classifyBlobError(err);
+    classified.cause = err;
+    throw classified;
+  }
+
+  const chunks = [];
+  for await (const chunk of response.readableStreamBody) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+/**
+ * Classify an Azure Blob error into a coarse category.
+ *
+ * @param {Error & { statusCode?: number, code?: string }} err
+ * @returns {'not-logged-in' | 'unauthorized' | 'not-found' | 'network-error' | 'transient'}
+ */
+export function classifyBlobError(err) {
+  const status = err.statusCode ?? err?.response?.status;
+  if (status === 401) return 'not-logged-in';
+  if (status === 403) return 'unauthorized';
+  if (status === 404) return 'not-found';
+  if (err.code === 'ENOTFOUND' || err.code === 'ECONNREFUSED' || err.code === 'EAI_AGAIN') {
+    return 'network-error';
+  }
+  return 'transient';
+}
+
+function userMessage(err) {
+  switch (classifyBlobError(err)) {
+    case 'not-logged-in':
+      return 'Not authenticated. Run `az login` (or sign in via VS Code / PowerShell) and try again.';
+    case 'unauthorized':
+      return 'Access denied. Your account does not have read access to the asset bundle. Contact your administrator.';
+    case 'not-found':
+      return 'Asset bundle not found in Azure Blob. Check blob.accountName and blob.containerName in sv-style.json.';
+    case 'network-error':
+      return 'Network error reaching Azure Blob. Check your internet connection and try again.';
+    default:
+      return `Azure Blob error: ${err.message || err}`;
+  }
+}