Karvey design graphic

Karvey Design Graphic

Purpose

With the approved mockup as the structural wireframe, define the complete visual design specification: color, typography, layout, motion, and micro-interactions. Update the mockup HTML with the defined visual system.

Execution steps

Step 1 — Load context

Read:

• docs/spec/changes/{change-id}/spec.json
• docs/spec/changes/{change-id}/mockup.html
• docs/spec/changes/{change-id}/proposal.md

Verify approvals.mockup.approved = true. If not, stop.

Check whether a PRODUCT.md or DESIGN.md exists in the project to understand the existing brand.

Step 2 — Identify the design register

Determine the product type:

Enterprise product (B2B, internal tool):

• Restrained palette, function over expressiveness
• High-legibility typography
• Minimal, non-distracting motion
• High information density

Consumer product (B2C, user experience):

• More expressive, brand-driven palette
• Typography with more personality
• Motion as part of the experience
• Moderate information density

Infer from proposal.md and spec.json.capability.

Target agnosticism (do NOT assume web). The design guidance depends on the target declared in docs/spec/project.json (see karvey/rules/targets.md):

• web → WCAG (contrast, focus, semantics, keyboard navigation)
• iOS → Apple Human Interface Guidelines (HIG) (Dynamic Type typography, safe areas, gestures, native controls)
• Android → Material Design (elevation, Material components, touch targets, theming)
• desktop → desktop conventions (density, menus, windows, OS shortcuts)
• cli/terminal → terminal conventions (column width, ANSI color, monospaced legibility, no assuming a GUI)

The color, typography, layout, and motion dimensions in the following steps are interpreted according to the target's guidance. If the project has multiple targets, define the visual system for each one while respecting its guidance. No phase assumes "web" by default.

Step 3 — Define color system (OKLCH)

Choose a palette strategy:

Restrained (recommended for B2B):

• 1 accent color, the rest neutrals
• Accent: oklch(55% 0.18 {hue})
• Neutrals: gray scale oklch(98% 0 0) → oklch(15% 0 0)

Committed:

• 1 primary color + 1 supporting color
• Primary: oklch(50% 0.20 {hue})
• Supporting: oklch(55% 0.15 {complementary hue})

Full palette:

• Primary, secondary, accent, and semantic colors
• Appropriate for products with differentiated visual roles

Always define:

• --color-primary: primary action, CTA
• --color-surface: card/panel background
• --color-background: page background
• --color-border: subtle borders
• --color-text-primary: primary text
• --color-text-secondary: supporting text
• --color-semantic-success: oklch(62% 0.17 145)
• --color-semantic-error: oklch(55% 0.22 25)
• --color-semantic-warning: oklch(75% 0.18 80)

Step 4 — Define typography

Choose 1-2 Google Fonts (or system fonts for B2B):

For enterprise B2B:

• Display/heading: Inter, DM Sans, or system-ui
• Body: same family, different weights

For B2C:

• Display: a font with character (Fraunces, Instrument Serif, Plus Jakarta Sans)
• Body: a high-legibility font (Inter, DM Sans)

Type scale:

--text-xs:   0.75rem / 1rem
--text-sm:   0.875rem / 1.25rem
--text-base: 1rem / 1.5rem
--text-lg:   1.125rem / 1.75rem
--text-xl:   1.25rem / 1.75rem
--text-2xl:  1.5rem / 2rem
--text-3xl:  1.875rem / 2.25rem

Step 5 — Define layout and spacing

4px-based spacing system:

--space-1: 4px   --space-2: 8px   --space-3: 12px
--space-4: 16px  --space-6: 24px  --space-8: 32px
--space-12: 48px --space-16: 64px --space-24: 96px

Product grid:

• Sidebar: fixed 240px (or 64px collapsed)
• Content area: fluid with max-width based on density
• Content columns: 12 columns with a 24px gap

Border radius:

--radius-sm: 4px   --radius-md: 8px
--radius-lg: 12px  --radius-xl: 16px  --radius-full: 9999px

Step 6 — Define motion

For B2B: functional motion, not decorative

--duration-fast: 100ms
--duration-base: 200ms
--duration-slow: 300ms
--ease-standard: cubic-bezier(0.4, 0, 0.2, 1)
--ease-enter: cubic-bezier(0, 0, 0.2, 1)
--ease-exit: cubic-bezier(0.4, 0, 1, 1)

Rule: use --duration-fast for feedback, --duration-base for transitions, --duration-slow for overlays.

Step 7 — Check for forbidden anti-patterns

Before writing the design-spec, confirm the system does NOT include:

• ❌ Decorative side-stripe borders (a color border on only one side of cards)
• ❌ Gradient text (text with a color gradient)
• ❌ Decorative glassmorphism (blur/transparency with no function)
• ❌ Card grids where every card is identical with no emphasis variation
• ❌ Hero metrics (a large number in the center of a screen as the only content)
• ❌ Backgrounds with noise patterns or excessive texture
• ❌ Animations longer than 500ms on frequent interactions

Step 7B — Design scoring 0-10 by dimension

Before finalizing the visual system, evaluate the design-spec/mockup with a 0-10 score for each relevant design dimension. The dimensions are interpreted according to the target's guidance (Step 2): WCAG for web, HIG for iOS, Material for Android, desktop/terminal conventions as applicable. Not all dimensions apply to all targets (e.g., "color/contrast" in a CLI is assessed over ANSI color; "motion" may not apply in a terminal).

Suggested dimensions (adjust to the target):

• Visual hierarchy — the eye finds what matters first; clear emphasis between primary/secondary/tertiary
• Typography — coherent scale, weights with purpose, legibility; on iOS respects Dynamic Type, in CLI monospaced legibility
• Color / contrast — intentional palette; sufficient contrast (WCAG AA/AAA on web; the target's equivalent)
• Spacing / rhythm — consistent base system, grouping by proximity, visual breathing room
• Consistency — reused tokens, uniform components, no ad-hoc values
• Accessibility — visible focus, keyboard navigation, touch targets, semantics; per the platform's checklist
• Motion — functional and non-distracting, reasonable durations, respects prefers-reduced-motion (or the target's equivalent)

For each dimension:

1. Assign a 0-10 score.
2. Explicitly explain what a 10 would be in that dimension for this design and target (the concrete bar for excellence, not a generic one).
3. State what is missing to reach a 10 from the current score (actionable gap).

Scoring table:

Dimension	Score (0-10)	What a 10 would be	What is missing to get there
Visual hierarchy
Typography
Color / contrast
Spacing / rhythm
Consistency
Accessibility
Motion

Acceptable threshold: average ≥ 8 and no dimension < 7. If not met, iterate the design-spec/mockup (return to steps 3-6 depending on the weak dimension) and re-evaluate. Repeat until the threshold is met or until the remaining gap is a conscious scope decision documented in the design-spec.

Step 8 — Write design-spec.md

# Design Spec: {change-id}

## Design register
{enterprise B2B | consumer B2C} — {rationale}

## Color system (OKLCH)
Strategy: {Restrained | Committed | Full palette}

| Token | OKLCH value | Use |
|-------|-------------|-----|
| --color-primary | oklch(...) | {use} |
| --color-surface | oklch(...) | {use} |
...

## Typography
| Token | Font | Weight | Use |
|-------|--------|------|-----|
| Heading | {font} | 600-700 | Page and section titles |
| Body | {font} | 400-500 | Content text |
| Caption | {font} | 400 | Metadata, labels |

## Type scale
(full table)

## Layout
- Sidebar: {fixed N px | collapsible | no sidebar}
- Grid: {description}
- Content max-width: {N px}

## Spacing
(4px base table)

## Border radius
(table)

## Motion
(variables table)

## Key components and their visual treatment
| Component | Surface | Border | Shadow | Hover state |
|------------|-----------|-------|--------|--------------|
| Primary button | | | | |
| Secondary button | | | | |
| Data card | | | | |
| Form input | | | | |
| Table row | | | | |
| Modal overlay | | | | |

## Anti-patterns avoided
(list of those that were checked)

## Design scoring (0-10 by dimension)
Target evaluated: {web (WCAG) | iOS (HIG) | Android (Material) | desktop | cli/terminal}

| Dimension | Score (0-10) | What a 10 would be | What is missing to get there |
|-----------|-------------|-----------------|-----------------------|
| Visual hierarchy | | | |
| Typography | | | |
| Color / contrast | | | |
| Spacing / rhythm | | | |
| Consistency | | | |
| Accessibility | | | |
| Motion | | | |

Average: {N}/10 — Threshold (≥8, none <7): {met | not met}
Iterations performed: {N} — Consciously accepted gaps: {description or "none"}

Write to docs/spec/changes/{change-id}/design-spec.md.

Step 9 — Update mockup.html with the visual system

Edit mockup.html to:

1. Add the CSS custom properties (:root { --color-primary: ...; ... })
2. Replace hardcoded colors with the variables
3. Add the font via Google Fonts @import
4. Apply the motion system to existing transitions
5. Update the banner: 🎨 MOCKUP WITH GRAPHIC DESIGN — {change-id} — {date}

Step 9B — Generate the visual components catalog

The design-spec.md defines the system at the token level (palette, type, spacing, key components with their treatment + scoring). It does not enumerate, screen by screen and component by component, the concrete visual assets an illustrator or an AI art agent must produce. That is what design-components.md is for: an art brief per component.

Derive it — do not invent it. The catalog is derived from three sources and must cover them exhaustively — nothing invented, nothing omitted:

• mockup.html (approved) — every screen, modal/bottom sheet, and state that actually appears.
• design-spec.md — palette (hex + OKLCH, light AND dark), typography, tokens, illustration register.
• proposal.md / requirements — the character/brand, the domain, and what each surface is for.

Target agnosticism (do NOT assume web). Adapt the components to the project's target(s) declared in docs/spec/project.json (see karvey/rules/targets.md). The component inventory changes with the target: mobile → screens, bottom sheets, bottom-nav, push notifications; web → pages, side-nav, toasts, tables; CLI → screens/prompts, states, ANSI treatment; etc. If the project has multiple targets, add a section per target (e.g. "App" + "WebApp"). No component is assumed just because the web default has it.

Write to docs/spec/changes/{change-id}/design-components.md using this template:

# Visual components catalog — {product / change-id}

**Purpose:** brief for a designer or AI agent that produces **illustrations/backgrounds per component**. Each item carries: what it is, content, states, and **required background art** (motif + style + palette). Navigable reference: `mockup.html`. Visual system: `design-spec.md`.

## Cross-cutting base (applies to all art)
- **Style:** {illustration style — trace, shapes, energy reference without copying any artist/brand}.
- **Palette (OKLCH → hex):** {light: hex list} · **Dark:** {dark: hex list}.
- **Character / brand:** {the hero of the art — how it can be illustrated across variants}.
- **Asset format:** vector/SVG preferred; PNG @1x/@2x/@3x for bitmap; backgrounds that **work in light and dark**; **safe zone** for text on top (do not saturate the center).

---

## A. Screens — {target / surface}

| # | Screen | Purpose | Required background/art |
|---|--------|---------|-------------------------|
| A1 | **{screen}** | {purpose} | {scene / motif / where the safe zone is} |
| … | | | |

## B. Modals / bottom sheets

| # | Modal | Content | Header illustration |
|---|-------|---------|---------------------|
| B1 | **{modal}** | {content} | {small header illustration} |
| … | | | |

## C. UI components

Per component: description, states, and **required background/fill art**. Cover at least: primary button, secondary button, input/textbox (+ variants: text, number, masked RUT/phone, select, date picker, textarea, search), chip, card, tile, avatar, badge, progress bar, tabs, bottom-nav (or the target's navigation), global states (loading/empty/error/success), and any **target-specific** component that appears in the mockup.

### C1. {component}
- **What it is:** {description}.
- **States:** {enumerate real states — normal, hover/pressed, disabled, loading, error, …}.
- **Art:** {required background/fill art, or "no illustration — define shine/shadow only"}.

### C2. {component}
- …

## D. Push notifications

| Type | Example copy | Illustration |
|------|--------------|--------------|
| **{type}** | "{copy in the product's voice}" | {icon/illustration} |
| … | | |

## E. {other surface — e.g. WebApp} (only if the change has it)

| Component | Description | Art |
|-----------|-------------|-----|
| **{component}** | {description} | {art} |

---

## F. Deliverable for the illustrator / AI agent
For each component in sections C, D and E, **1 base illustration** is expected (+ state variants where indicated), in the palette and style of "Cross-cutting base", with a **light and dark** version and a **safe zone for text**. Priority order:
1. {highest-visibility assets — e.g. hero scene + hero portrait}.
2. {navigation + tile/chip icon sets}.
3. {push notification icons}.
4. {badges / progress / accents}.
5. {modals and global states}.

Only include sections that the change actually has (drop E if there is no second surface; rename A's heading to the real target). Every screen/modal/state present in mockup.html must appear here.

Step 9C — Update knowledge graph

Sync the knowledge per karvey/rules/knowledge-sync.md (Obsidian if available; at minimum /graphify docs/spec/ --update) to reflect design-spec.md, design-components.md, and the updated mockup.html. If docs/spec/graphify-out/ does not exist, invoke /graphify docs/spec/ without --update.

Step 10 — Output

✅ Design spec generated

Files created/updated:
  - docs/spec/changes/{change-id}/design-spec.md
  - docs/spec/changes/{change-id}/design-components.md
  - docs/spec/changes/{change-id}/mockup.html (updated with visual system)

Design system:
  - Register: {B2B/B2C}
  - Color strategy: {name}
  - Typography: {font(s)}
  - Anti-patterns checked: ✅
  - Design scoring: {N}/10 average (threshold ≥8, none <7) — {met | not met}
  - Components catalog: {N} components briefed (light+dark, safe zones)

Update spec.json: approvals.design_graphic = true

Next step:
/karvey-architecture {change-id}

Update spec.json: approvals.design_graphic.approved: true, phase: "design-graphic-approved".

Advance to the next phase

When you finish this phase and have the corresponding approval, actively ask the user: "Shall we advance to the Architecture phase now?"

• If they confirm → run /karvey-architecture {change-id}.
• If they prefer to review or adjust first → wait. Advancing is always with the user's OK (the method's gate).
• If you resume in another session, /karvey {change-id} shows which phase you are in and which one is next.

---

Part of the Karvey™ Method — © HainTech, by Mauricio Quezada Ibáñez · Apache 2.0 · see karvey/LICENSE and karvey/TRADEMARK.md.