design system token v0.7

2026-04-16 13:04:38 -05:00
parent 9a311ff9a5
commit 18c15a6437
13 changed files with 768 additions and 25 deletions
--- a/README.md
+++ b/README.md
@@ -25,9 +25,11 @@ greyhaven-design-system/
 │   ├── radii.json
 │   ├── shadows.json
 │   └── motion.json
-├── skill/                  # Claude Skill (auto-generated)
-│   ├── SKILL.md
-│   └── install.sh
+├── skill/                  # AI skills
+│   ├── SKILL.md            # Design system reference (auto-generated)
+│   ├── AGENTS.md           # Project instructions (auto-generated)
+│   ├── BRAND.md            # Voice/tone/messaging (hand-curated, opt-in)
+│   └── install.sh          # Installer (supports --brand-skill flag)
 ├── mcp/                    # MCP server for AI agents
 │   └── server.ts
 ├── stories/                # Storybook stories (23 files, 8 categories)
@@ -55,20 +57,25 @@ greyhaven-design-system/

 ## Using the Design System with AI

-The design system provides three things for AI agents:
+The design system provides four things for AI agents:

 | File | What it is | Where it goes |
 |------|-----------|---------------|
 | **SKILL.md** | Full design system reference (tokens, all components, composition rules, extension protocol) | `.claude/skills/` — works in Claude Code, Cursor, OpenCode, Anigravity, etc. |
 | **AGENTS.md** | Short project instructions telling the AI *how* to use the design system (follows the [agents.md](https://agents.md) convention) | Project root — copy as `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, or `.github/copilot-instructions.md` |
-| **MCP Server** | Runtime tools for looking up components, validating colors, suggesting components | Configured in `.mcp.json` |
+| **BRAND.md** *(opt-in)* | Voice/tone/messaging rules for generating marketing copy, CTAs, product explanations. Hand-curated from the brand guidelines. | `.claude/skills/greyhaven-brand.md` — opt in via `--brand-skill` flag |
+| **MCP Server** | Runtime tools for looking up components, validating colors, suggesting components, fetching brand rules, validating copy | Configured in `.mcp.json` |

-All are auto-generated from the same sources (`tokens/*.json` and `lib/catalog.ts`).
+SKILL.md and AGENTS.md are auto-generated from `tokens/*.json` and `lib/catalog.ts`. BRAND.md is hand-curated from `vibedocs/greyhaven-brand-system.md`.

 ### Quick Install (all at once)

 ```bash
+# Default: SKILL.md + AGENTS.md + fonts
 ./skill/install.sh /path/to/your/project
+
+# With brand skill: also install BRAND.md + logo SVGs
+./skill/install.sh /path/to/your/project --brand-skill
 ```

 This **copies** (not symlinks) the following into your project:
@@ -76,6 +83,11 @@ This **copies** (not symlinks) the following into your project:
 2. `AGENTS.md` → project root (project-level instructions)
 3. Aspekta font files → `public/fonts/`

+With `--brand-skill`, additionally:
+
+4. `BRAND.md` → `.claude/skills/greyhaven-brand.md` (voice/tone/messaging)
+5. Logo SVGs → `public/logos/` (file names normalized: `gh-logo-positive-full-black.svg`, `gh-symbol-full-black.svg`, etc.)
+
 The script also prints the CSS `@font-face` block and MCP server config to add next.

 **Re-run the script after design system updates** to refresh your copies.
@@ -119,9 +131,34 @@ cp /path/to/greyhaven-design-system/skill/AGENTS.md /path/to/your/project/.githu

 Or use the install script, which copies `AGENTS.md` to the project root automatically.

+### BRAND.md (voice, tone, messaging)
+
+BRAND.md is an **opt-in** skill for projects that generate user-facing content — marketing copy, landing pages, CTAs, product explanations, emails. It codifies the Greyhaven brand voice: direct, plain-spoken, engineering-flavored, no hype, no sales language.
+
+It's **not installed by default** because most projects only need the design system components, not brand voice rules.
+
+**Install via the `--brand-skill` flag:**
+
+```bash
+./skill/install.sh /path/to/your/project --brand-skill
+```
+
+This adds:
+- `skill/BRAND.md` → `.claude/skills/greyhaven-brand.md` (brand skill)
+- Greyhaven logo SVGs → `public/logos/` (full logos + symbol-only + product lockups, in black and white variants, file names normalized)
+
+Once installed, AI agents in your project can reference the brand skill when generating copy. The skill covers:
+- Core positioning and the three brand axes (containment, human-centered, engineered)
+- Tone of voice rules
+- Writing patterns (plain-language engineering, no hype)
+- Reasoning patterns (cause→effect, constraint→outcome, observation→explanation, finite scope→concrete result)
+- CTA guidance (good vs. bad patterns)
+- Logo usage rules
+- A self-check list to run before shipping any copy
+
 ### Option C: MCP Server

-The MCP server provides 5 tools for programmatic access:
+The MCP server provides 7 tools for programmatic access:

 | Tool | Description |
 |------|-------------|
@@ -130,8 +167,10 @@ The MCP server provides 5 tools for programmatic access:
 | `list_components(category?)` | Lists components (all, or by: primitives, layout, overlay, navigation, data, feedback, form, composition) |
 | `validate_colors(code)` | Checks code for raw hex values that should use design tokens |
 | `suggest_component(description)` | Suggests components for a described UI need |
+| `get_brand_rules(section?)` | Returns brand voice/tone/messaging rules. Section can be: `positioning`, `axes`, `tone`, `writing-rules`, `reasoning-patterns`, `cta`, `logo`, `self-check`, or `all` |
+| `validate_copy(text)` | Lints marketing copy for hype words, sales language, vague superlatives, urgency framing, and exclamation marks |

-Plus resources: `tokens://all` and `component://{name}` for each component.
+Plus resources: `tokens://all`, `component://{name}` for each component, and `brand://guidelines` for the full brand skill.

 **Run directly:**

@@ -224,7 +263,7 @@ pnpm build-storybook   # Static build
 | `pnpm storybook` | Storybook dev server on :6006 |
 | `pnpm build-storybook` | Static Storybook build |
 | `pnpm tokens:build` | Regenerate CSS/TS/MD from token JSON files |
-| `pnpm skill:build` | Regenerate skill/SKILL.md from tokens + catalog |
+| `pnpm skill:build` | Regenerate skill/SKILL.md and skill/AGENTS.md from tokens + catalog |
 | `pnpm mcp:start` | Start the MCP server (stdio transport) |
 | `pnpm mcp:build` | Type-check MCP server |
 | `pnpm lint` | Run ESLint |