brandspec 0.1.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "brandspec",
+  "version": "0.1.0",
+  "description": "Define Brand Identity as code. CLI for creating, validating, and generating brand tokens.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "brandspec": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "schema",
+    "workshop"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup --config cli/tsup.config.ts",
+    "dev": "tsup --config cli/tsup.config.ts --watch",
+    "typecheck": "tsc -p cli/tsconfig.json --noEmit",
+    "test": "node --test cli/test/*.test.mjs",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "js-yaml": "^4.1.0",
+    "jszip": "^3.10.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "brandspec",
+    "brand",
+    "identity",
+    "design-tokens",
+    "yaml",
+    "workshop",
+    "ai"
+  ],
+  "license": "MIT",
+  "homepage": "https://brandspec.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brandspec/brandspec"
+  }
+}

package/schema/spec/assets.md

@@ -0,0 +1,219 @@
+# Assets Specification
+
+Machine-readable specification for the `assets` section of brand.yaml.
+
+## Structure
+
+```yaml
+assets:
+  - file: "path/to/file.svg"       # Required. Relative to brandspec/.
+    id: "logo-primary"             # Recommended. Unique semantic identifier.
+    role: "logo"                   # Recommended. What the asset is.
+    variant: "primary"             # Optional. Which variation.
+    context: "light-bg"            # Optional. Usage context.
+    description: "Primary logo"    # Optional. Human-readable description.
+    formats: [...]                 # Optional. Derived formats.
+    tags: [...]                    # Optional. Free-form tags.
+```
+
+Only `file` is required. A minimal valid entry:
+
+```yaml
+assets:
+  - file: logo.svg
+```
+
+---
+
+## Fields
+
+### `file` (required)
+
+Relative file path from `brandspec/` directory.
+
+### `id` (recommended)
+
+Unique semantic identifier for programmatic access. Use `{role}-{variant}` pattern.
+
+### `role` (recommended)
+
+What the asset is used for.
+
+| Role | Description |
+|------|-------------|
+| `logo` | Main logo (may include wordmark) |
+| `wordmark` | Text-only logo |
+| `symbol` | Icon/symbol mark (no text) |
+| `icon` | Small icon (app icon, etc.) |
+| `favicon` | Browser favicon |
+| `graphic` | General graphic asset |
+| `pattern` | Repeating pattern/texture |
+| `photo` | Photography |
+| `illustration` | Illustrations |
+| `video` | Video content |
+| `audio` | Audio (sound logo, etc.) |
+| `document` | Documents (guidelines PDF, etc.) |
+| `font` | Font files |
+
+Custom values are allowed.
+
+### `variant` (optional)
+
+Which variation of the asset.
+
+| Variant | Description |
+|---------|-------------|
+| `primary` | Main version |
+| `secondary` | Alternative version |
+| `monochrome` | Single color |
+| `inverse` | Inverted (for dark backgrounds) |
+| `simplified` | Simplified version (small sizes) |
+| `vertical` | Vertical layout |
+| `horizontal` | Horizontal layout |
+
+Custom values are allowed.
+
+### `context` (optional)
+
+Intended usage context.
+
+| Context | Description |
+|---------|-------------|
+| `light-bg` | For light backgrounds |
+| `dark-bg` | For dark backgrounds |
+| `any` | Works on any background |
+| `print` | For print use |
+| `digital` | For digital/screen use |
+| `social` | For social media |
+
+### `formats` (optional)
+
+Derived formats (different sizes, file types):
+
+```yaml
+formats:
+  - path: assets/logo-primary.png
+    width: 800
+    height: 200
+  - path: assets/logo-primary@2x.png
+    width: 1600
+    height: 400
+```
+
+### `tags` (optional)
+
+Free-form tags for categorization:
+
+```yaml
+tags: [header, official, print, marketing]
+```
+
+---
+
+## File Naming Convention
+
+Pattern: `{role}-{variant}[-{context}].{ext}`
+
+| Example | Role | Variant | Context |
+|---------|------|---------|---------|
+| `logo-primary.svg` | logo | primary | — |
+| `logo-monochrome.svg` | logo | monochrome | — |
+| `logo-inverse-dark-bg.svg` | logo | inverse | dark-bg |
+| `favicon.ico` | favicon | — | — |
+| `symbol-simplified.svg` | symbol | simplified | — |
+
+---
+
+## Directory Structure
+
+```
+brandspec/
+├── brand.yaml
+└── assets/
+    ├── logo-primary.svg
+    ├── logo-monochrome.svg
+    ├── logo-inverse.svg
+    ├── symbol.svg
+    ├── favicon.ico
+    └── icon-app.png
+```
+
+Assets are stored in `brandspec/assets/` and referenced from `brand.yaml` with relative paths.
+
+---
+
+## Logo System Patterns
+
+Brands use one of four fundamental logo system patterns. Each determines required assets.
+
+### Pattern A: Wordmark
+
+Typography is the identity. Text-only or stylized text mark.
+
+| Attribute | Detail |
+|-----------|--------|
+| Examples | Google, FedEx, Coca-Cola, Supreme, IBM |
+| Best for | Strong names, text-centric brands |
+| Required assets | `wordmark` (+ variants) |
+
+### Pattern B: Symbol + Wordmark (separated)
+
+Independent symbol and wordmark, used separately or combined.
+
+| Attribute | Detail |
+|-----------|--------|
+| Examples | Apple, Nike, Spotify, Slack, Airbnb |
+| Best for | Apps needing an icon, long-term symbol recognition |
+| Required assets | `symbol`, `wordmark` |
+| Optional assets | `logo-horizontal`, `logo-vertical` (combined layouts) |
+
+### Pattern C: Combination Mark (integrated)
+
+Symbol and text form a single inseparable unit.
+
+| Attribute | Detail |
+|-----------|--------|
+| Examples | Adidas, Burger King, Lacoste |
+| Best for | Early-stage brands, consistency priority |
+| Required assets | `logo` (integrated unit) |
+| Optional assets | `symbol` (extracted for favicon) |
+
+### Pattern D: Emblem
+
+Text enclosed within or integral to a shape.
+
+| Attribute | Detail |
+|-----------|--------|
+| Examples | Starbucks, BMW, NFL, university crests |
+| Best for | Heritage, authority, luxury, institutional |
+| Required assets | `logo` (full emblem) |
+| Optional assets | `logo-simplified` (reduced detail for small sizes) |
+
+### Pattern Summary
+
+> Shorthand names map to `role` + `variant` fields (e.g. `logo-simplified` = `role: logo, variant: simplified`).
+
+```yaml
+logo_system_patterns:
+  wordmark:
+    required: [wordmark]
+  symbol_wordmark:
+    required: [symbol, wordmark]
+    optional: [logo-horizontal, logo-vertical]
+  combined:
+    required: [logo]
+    optional: [symbol]
+  emblem:
+    required: [logo]
+    optional: [logo-simplified]
+```
+
+### Recommended Variants (all patterns)
+
+| Variant | Purpose | Priority |
+|---------|---------|----------|
+| `primary` | Standard use on light backgrounds | Required |
+| `inverse` | Use on dark backgrounds | High |
+| `monochrome` | Single-color constraints | High |
+| `simplified` | Small sizes (favicon, 16–32px) | Medium |
+| `vertical` / `horizontal` | Layout variants (Pattern B: symbol + wordmark combined) | Pattern B only |

package/schema/spec/core.md

@@ -0,0 +1,203 @@
+# Core Specification
+
+Machine-readable specification for the `core` section of brand.yaml.
+
+Defines the brand's verbal identity: essence, personality, voice, and strategic statements.
+
+## Structure
+
+```yaml
+core:
+  essence: "..."           # Internal guiding principle. One sentence.
+  tagline: "..."           # Public-facing copy. One line.
+  mission: "..."           # Why the brand exists.
+  vision: "..."            # What the brand aspires to become.
+  values:                  # Core beliefs that drive decisions.
+    - "..."
+  personality:             # 3-5 adjectives describing the brand character.
+    - "..."
+  voice:                   # How the brand speaks.
+    tone:
+      - "..."
+    principles:
+      - "..."
+```
+
+Only `meta.name` is required for a valid brandspec. All `core` fields are optional at the schema level.
+
+---
+
+## Fields
+
+### `essence` (recommended)
+
+One sentence capturing the brand's internal guiding principle. Used as a north star for decisions, not shown to end users directly.
+
+```yaml
+essence: "Make brand identity accessible to every builder"
+```
+
+Rules:
+- Single sentence, concise
+- Internal-facing (guides decisions, not marketing copy)
+- Distinct from `tagline` (which is public-facing)
+
+### `tagline` (recommended)
+
+Public-facing copy that captures the brand promise. One line.
+
+```yaml
+tagline: "Brand clarity, delivered"
+```
+
+Rules:
+- Short, memorable
+- External-facing (marketing, website, social)
+- Distinct from `essence` (which is internal)
+
+### `mission` (optional)
+
+Why the brand exists. What it does and for whom.
+
+```yaml
+mission: "To give every team a single source of truth for their brand identity"
+```
+
+### `vision` (optional)
+
+What the brand aspires to become or achieve long-term.
+
+```yaml
+vision: "A world where every product ships with a consistent, intentional brand"
+```
+
+### `values` (optional)
+
+Array of strings. Core beliefs that drive brand decisions.
+
+```yaml
+values:
+  - "Simplicity over complexity"
+  - "Openness by default"
+  - "Craft in every detail"
+```
+
+### `personality` (recommended)
+
+Array of 3-5 adjectives describing the brand character. These inform voice, visual choices, and content tone.
+
+```yaml
+personality:
+  - innovative
+  - approachable
+  - confident
+  - playful
+```
+
+Rules:
+- 3-5 adjectives
+- Ordered by prominence (most defining trait first)
+- Used as input for voice tone and visual direction
+
+### `voice` (optional)
+
+Object defining how the brand speaks. Contains two sub-fields:
+
+```yaml
+voice:
+  tone:
+    - friendly
+    - clear
+    - encouraging
+  principles:
+    - "Use active voice"
+    - "Keep sentences short"
+    - "Celebrate user wins"
+```
+
+#### `voice.tone` (string[])
+
+Adjectives describing the emotional quality of brand communication. Overlaps with `personality` but focuses specifically on written/spoken communication.
+
+#### `voice.principles` (string[])
+
+Actionable writing rules the brand follows. Each principle should be a concrete, checkable guideline.
+
+> **Note:** The schema allows additional keys on `voice` for extensibility, but only `tone` and `principles` are standard. Linting may warn on unrecognized keys.
+
+---
+
+## Required vs Recommended
+
+| Field | Level | Rationale |
+|-------|-------|-----------|
+| `essence` | Recommended | Core guiding principle — high value for brand consistency |
+| `tagline` | Recommended | Public-facing identity — needed for most touchpoints |
+| `personality` | Recommended | Drives voice and visual decisions across phases |
+| `mission` | Optional | Useful but not needed for visual/verbal output |
+| `vision` | Optional | Useful but not needed for visual/verbal output |
+| `values` | Optional | Useful but not needed for visual/verbal output |
+| `voice` | Optional | Can be derived from personality if not explicitly set |
+
+The Workshop recommends defining at least `essence`, `tagline`, and `personality` during Phase 2 (Concept).
+
+---
+
+## Voice: What Goes Where
+
+The `core.voice` object defines **tone** and **principles** only.
+
+Do/Don't examples, specific copywriting rules, and detailed voice enforcement belong in the `guidelines` section as structured rules:
+
+```yaml
+# core section — tone and principles
+core:
+  voice:
+    tone: [friendly, clear]
+    principles:
+      - "Use active voice"
+      - "Keep sentences short"
+
+# guidelines section — enforceable voice rules with examples
+guidelines:
+  voice-examples:
+    content: |
+      ## Voice Examples
+      - Greeting: "Hey there!" (not "Dear user")
+      - Error: "Something went wrong" (not "Error 500")
+    rules:
+      - id: "voice-active"
+        description: "Copy uses active voice"
+        severity: warning
+        applies_to: voice
+      - id: "voice-no-jargon"
+        description: "No technical jargon in user-facing messages"
+        severity: warning
+        applies_to: voice
+```
+
+This separation keeps `core` as a concise identity definition and `guidelines` as the enforceable rulebook.
+
+---
+
+## Extensions
+
+For brand phrases, copy collections, or verbal identity elements that don't fit the standard `core` fields, use the top-level `extensions` section:
+
+```yaml
+extensions:
+  copy:
+    key_phrase: "Build brands that last"
+    cta_primary: "Get started"
+    cta_secondary: "See examples"
+  naming:
+    rationale: "Evokes clarity, multiple facets, light/modern feel"
+    alternatives_considered:
+      - "BrandSync"
+      - "AssetHub"
+```
+
+Rules:
+- Use `extensions` for non-standard verbal identity content
+- `extensions` is fully open (`additionalProperties: true`)
+- Naming rationale belongs in `extensions.naming` or `_workshop/decisions.yml`, not in `core`

package/schema/spec/guidelines.md

@@ -0,0 +1,110 @@
+# Guidelines Specification
+
+Machine-readable specification for the `guidelines` section of brand.yaml.
+
+## Structure
+
+Each key under `guidelines` is a named guideline section containing free-form content and optional machine-readable rules:
+
+```yaml
+guidelines:
+  logo-usage:
+    content: |
+      ## Logo Usage
+      Markdown content for human readers...
+    rules:
+      - id: "logo-min-size"
+        description: "Logo must meet minimum size requirements"
+        severity: error
+        applies_to: logo
+        criteria:
+          - "Digital usage: minimum 120px width"
+          - "Print usage: minimum 25mm width"
+```
+
+---
+
+## Fields
+
+### `content` (recommended)
+
+Free-form Markdown string. Human-readable guidelines for a specific topic.
+
+Typical sections: logo usage, color usage, voice & tone examples.
+
+### `rules` (optional)
+
+Array of structured, machine-readable rules for AI-driven brand linting.
+
+Each rule:
+
+```yaml
+- id: "rule-id"              # Recommended. Unique rule identifier.
+  description: "..."         # Required. What this rule enforces.
+  severity: error            # Required. info | warning | error.
+  applies_to: "logo"        # Optional. Target: logo, color, typography, voice.
+  criteria:                  # Optional. Specific checkable conditions.
+    - "Condition 1"
+    - "Condition 2"
+```
+
+### Severity Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| `info` | Advisory, best practice | No action required |
+| `warning` | Should fix, non-critical | Review recommended |
+| `error` | Must fix, violation | Requires resolution |
+
+---
+
+## Common Guideline Sections
+
+### `logo-usage`
+
+Typical rules:
+
+| Rule ID | Description | Severity |
+|---------|-------------|----------|
+| `logo-min-size` | Minimum size requirements (120px digital, 25mm print) | error |
+| `logo-clear-space` | Clear space around logo | warning |
+| `logo-no-rotation` | Logo must not be rotated | error |
+| `logo-no-effects` | No shadows, gradients, or effects applied to logo | error |
+| `logo-no-distortion` | Aspect ratio must match original | error |
+
+### `color-usage`
+
+Typical rules:
+
+| Rule ID | Description | Severity |
+|---------|-------------|----------|
+| `color-contrast-aa` | Text on brand colors meets WCAG AA (4.5:1 normal, 3:1 large) | error |
+| `color-secondary-area` | Secondary color not used for large background areas (>30% viewport) | warning |
+
+### `voice-examples`
+
+Typical rules:
+
+| Rule ID | Description | Severity |
+|---------|-------------|----------|
+| `voice-active` | Copy uses active voice | warning |
+| `voice-no-jargon` | No technical jargon in user-facing messages | warning |
+| `voice-button-descriptive` | Button labels describe the action (not "Submit", "Click here") | error |
+
+---
+
+## Extensions and Core Sections
+
+The `guidelines` key is for usage rules about the brand.
+
+For brand-specific metadata that doesn't fit standard sections, use the top-level `extensions` section:
+
+```yaml
+extensions:
+  social:
+    twitter: "@brand"
+    linkedin: "company/brand"
+  legal:
+    trademark: "Brand™"
+    copyright: "© 2026 Brand Inc."
+```