Branding & Design

Maistik Spec Kit includes a full design specification system. Define your product's visual identity as structured specs, then create UI component and user flow specs that reference those tokens.

Overview

Branding Specification

Command: /speckit.brand

Define the visual foundation for your product.

/speckit.brand Modern SaaS app with teal primary, clean sans-serif typography, 4px spacing grid

The command walks you through each section interactively:

What It Covers

Color Palette

Primary, secondary, accent, and status colors (success, error, warning, info). Each with light and dark theme variants.

| Token | Light Mode | Dark Mode | Usage |
|-------|-----------|-----------|-------|
| `color-primary` | #0EA594 | #2DD4BF | Buttons, links, active states |
| `color-secondary` | #6366F1 | #818CF8 | Secondary actions, accents |

Typography

Font families (headings, body, monospace), size scale (xs through 4xl), weight scale, and line-height ratios.

| Scale | Size | Line Height | Usage |
|-------|------|-------------|-------|
| `text-sm` | 14px / 0.875rem | 1.43 | Captions, helper text |
| `text-base` | 16px / 1rem | 1.5 | Body text |
| `text-lg` | 18px / 1.125rem | 1.56 | Subtitles |

Spacing & Layout

Base unit (typically 4px), spacing scale, grid system, and responsive breakpoints.

Additional Tokens

• Shadows & Elevation — depth levels (sm, md, lg, xl)
• Borders & Radius — widths and corner radius scale
• Motion — animation durations, easing curves, transition defaults
• Iconography — icon style, library, sizing

Output

• .specify/branding/branding.md — human-readable design specification
• .specify/branding/tokens.json — machine-readable tokens for build tools

Design Specification

Command: /speckit.design

Create UI component specs and user flow specs for a feature. Reads the branding spec for context.

/speckit.design Design the project dashboard with nav sidebar, stats cards, and activity feed

Component Specs

For each UI component, the design spec defines:

Section	Content
Variants	Visual variations (default, outline, ghost, destructive, etc.)
Sizes	sm, md, lg, icon
States	Default, hover, active, disabled, loading, focus
Accessibility	ARIA roles, keyboard interactions, contrast requirements
BDD Scenarios	GIVEN/WHEN/THEN acceptance criteria per variant
Props	Component API with types and defaults
Tokens Used	Which branding tokens this component references

Example component spec:

### Component: Button

| Variant | Background | Text | Border |
|---------|-----------|------|--------|
| Primary | `color-primary` | `color-on-primary` | none |
| Secondary | transparent | `color-primary` | `color-primary` |
| Ghost | transparent | `color-text-secondary` | none |
| Destructive | `color-error` | `color-on-error` | none |

#### Scenario: Primary button hover
- GIVEN a primary button is rendered
- WHEN the user hovers over it
- THEN the background changes to `color-primary-hover`
- AND the cursor becomes a pointer

User Flow Specs

For user journeys:

Section	Content
Entry Points	How users reach this flow
Steps	Numbered sequence with screen descriptions
Decision Points	Branching logic (if/else paths)
Error States	What happens when things go wrong
Success Criteria	Measurable outcomes
ASCII Wireframes	Optional text-based screen layouts

Validation

The design command validates:

• All color references exist in branding.md
• Contrast ratios meet WCAG 2.1 AA standards (4.5:1 for text, 3:1 for large text)
• Components include accessibility requirements (ARIA, keyboard, focus)
• User flows have error state coverage

Integration with Analysis

When you run /speckit.analyze, the analysis includes a Design & Branding Consistency check:

• Hardcoded colors instead of token references
• Tokens referenced in design.md that don't exist in branding.md
• Missing accessibility requirements
• User flows missing error states
• WCAG contrast failures

Workflow

1. /speckit.brand             → Define visual identity
2. /speckit.specify           → Define feature requirements
3. /speckit.design            → Design the UI for that feature
4. /speckit.plan              → Plan the technical implementation
5. /speckit.analyze           → Verify design consistency
6. /speckit.implement         → Build it

The branding spec is created once. Design specs are created per feature, referencing the same tokens.