visual-identity

name	visual-identity
description	Produce a coherent visual identity (palette, typography, spacing, radius) from a brief and serialise to JSON for the design-tokens skill. Use when establishing brand identity.

SKILL: visual-identity

Purpose

Produce a coherent visual identity from a brief or set of brand keywords. Outputs are palette, typography pairing, spacing scale, and radius scale — all serialised to JSON files that feed the design-tokens skill. Human approval required before tokens propagate to UI.

Inputs

Field	Source	Example
brief	free-text brand description	"modern fintech, trustworthy, minimal"
keywords	3–6 brand keywords	["trust", "clarity", "speed"]
primary_color	optional hex override	"#2563eb"
existing_tokens	path to existing tokens.json	docs/design/identity/tokens.json

Outputs

File	Location	Description
palette.json	docs/design/identity/	All color roles with hex + WCAG contrast
typography.json	docs/design/identity/	Font families, scale, weights, line-heights
tokens.json	docs/design/identity/	W3C DTCG format — canonical token file

Target awareness

When design.target (project.config.yaml, default web) is tui, keep the same JSON outputs but constrain choices to the terminal: colors must be expressible in ANSI-256 (record the nearest 256 index alongside each hex), every fg/bg role pair must clear WCAG 2.2 AA contrast, and typography.json describes terminal text styles (bold, dim/faint, italic, underline, reverse) rather than font families and px sizes. The palette/typography/scale templates below still apply structurally; adapt their values for the terminal.

Palette Structure

docs/design/identity/palette.json:

{
  "brand": {
    "primary":   { "value": "#2563eb", "on": "#ffffff", "contrast_aa": true },
    "secondary": { "value": "#7c3aed", "on": "#ffffff", "contrast_aa": true },
    "accent":    { "value": "#0ea5e9", "on": "#ffffff", "contrast_aa": true }
  },
  "semantic": {
    "success"         
             
               
                
  
   
      
     
     
     
     
     
     
     
     
     
  
   
     
     
          
         
  

WCAG Contrast Check

All palette entries with on values must pass WCAG 2.2 AA (4.5:1 for normal text, 3:1 for large text):

def relative_luminance(hex_color):
    r, g, b = (int(hex_color[i:i+2], 16) / 255 for i in (1, 3, 5))
    def linearize(c):
        return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
    r, g, b = linearize(r), linearize(g), linearize(b)
    return 0.2126 * r + 0.7152 * g + 0.0722 * b

def contrast_ratio(fg, bg):
    l1 = relative_luminance(fg)
    l2 = relative_luminance(bg)
    lighter, darker = max(l1, l2), min(l1, l2)
    return (lighter + 0.05) / (darker + 0.05)

# AA normal text requires >= 4.5
# AA large text requires >= 3.0
ratio = contrast_ratio("#2563eb", "#ffffff")
assert ratio >= 4.5, f"FAIL: contrast {ratio:.2f} < 4.5 for #2563eb on #ffffff"

If any pair fails AA, adjust the shade until it passes. Never ship a palette with failing contrast.

Typography Structure

docs/design/identity/typography.json:

{
  "families": {
    "sans":  "Inter, system-ui, -apple-system, sans-serif",
    "mono":  "JetBrains Mono, 'Fira Code', monospace",
    "serif": null
  },
  "scale": {
    "xs":   { "size": "0.75rem",  "line": "1rem" },
    "sm":   { "size": "0.875rem", "line": "1.25rem" },
    "base": { "size": "1rem",     "line": "1.5rem" },
    "lg":        
             
             
           
            
  
   
     
      
     
        
  

Spacing + Radius Scales

Written directly into tokens.json (see design-tokens skill for full schema):

{
  "spacing": {
    "1":  "0.25rem",
    "2":  "0.5rem",
    "3":  "0.75rem",
    "4":  "1rem",
    "6":  "1.5rem",
    "8":  "2rem",
    "12": "3rem",
    "16": "4rem"
  },
  "radius": {
    "none": "0",
    "sm":   "0.125rem",
    "md":   "0.375rem",
    "lg":   "0.5rem",
    "xl":   "0.75rem",
     
  

Write palette.json

mkdir -p docs/design/identity
# Write palette.json from the template above, populated with chosen values
# Then validate all contrast ratios before writing
python3 scripts/validate-palette.py docs/design/identity/palette.json

Approval Gate

Mark docs/design/identity/palette.json approved before design-tokens runs:

Add to the top of palette.json:

{ "_meta": { "status": "draft", "approved_by": null, "approved_at": null }, ... }

Check in design-tokens skill:

STATUS=$(python3 -c "import json; print(json.load(open('docs/design/identity/palette.json'))['_meta']['status'])")
[ "$STATUS" = "approved" ] || { echo "BLOCKED: palette not approved"; exit 1; }

Failure Modes

Condition	Action
Contrast ratio fails AA	Adjust shade. Re-check. Never skip.
existing_tokens provided	Merge: only fill missing roles; do not overwrite approved values.
No brief or keywords provided	Generate a neutral/professional default palette. Log DEFAULT_PALETTE.
palette.json exists and is approved	Do not overwrite. Log SKIP — approved identity exists.

Logging

[visual-identity] PALETTE    docs/design/identity/palette.json  contrast=all-pass
[visual-identity] TYPOGRAPHY docs/design/identity/typography.json
[visual-identity] SKIP       docs/design/identity/palette.json  (approved — locked)
[visual-identity] CONTRAST_FAIL  #2563eb on #ffffff  ratio=3.8  required=4.5