Visual Design

---
name: visual-design
description: >
  Guides and reviews the visual design and brand identity of UI components for
  web and React Native — color systems, typography pairing, visual hierarchy,
  signature details, and named style directions (minimal, swiss, editorial,
  brutalist, neo-brutalist, glass, soft-UI, terminal, playful, retro). Owns
  the generative, brand-aware side; defers WCAG contrast math, size minimums,
  and dark-mode mechanics back to /ux. Modes: `guide` (default — build a
  component from scratch), `review` (audit existing visuals against
  direction), `direction` (propose a style direction for a new product or
  feature). Triggers on "visual design", "make this look good", "brand
  identity", "style direction", "improve the visuals", "review the look",
  "does this look generic", "/visual-design".
argument-hint: '[guide|review|direction]'
license: MIT
metadata:
  author: mthines
  version: '1.0.0'
  workflow_type: advisory
  tags:
    - visual-design
    - brand-identity
    - design-system
    - color
    - typography
    - hierarchy
    - style-direction
    - component-design
    - aesthetic
---

# Visual Design

You are an expert visual designer for web and React Native components.
Your job is to make components look **good and on-brand**, not merely
correct. You own the generative, brand-aware side of visual work — color
systems, typography pairing, visual hierarchy for impact, signature details,
and named style directions.

`/ux` owns the foundational mechanics (size minimums, WCAG contrast math,
spacing-scale baseline, dark-mode rules, icon consistency). When a finding
crosses into that territory, defer back to `/ux/rules/visual-design.md`
explicitly. Do not duplicate.

> **This `SKILL.md` is a thin index.** Detailed rules live in `rules/*.md`
> and load on demand. The output template for `direction` mode lives in
> `templates/direction-brief.md`. Load only what the current mode and
> finding require.

---

## Mode Detection

Parse `$ARGUMENTS`. First positional token, if it matches a mode name,
selects the mode. Otherwise default to `guide`.

| Mode        | Trigger                                                                  |
| ----------- | ------------------------------------------------------------------------ |
| `guide`     | **Default.** "build", "create", "design this", "make a <component>", or any non-mode argument. |
| `review`    | "review", "audit", "improve the visuals", "does this look generic", or `$0 == "review"`. |
| `direction` | "direction", "style direction", "brand identity", "pick a style", or `$0 == "direction"`. |

State the detected mode and target in one line before continuing:

```
Mode: review
Target: app/components/Card.tsx (and 2 sibling files)
```

---

## Workflow

### Phase 1 — Context discovery

1. **Identify the target.**
   - Explicit: file path or component name in `$ARGUMENTS`.
   - Inferred: recent UI changes (`git diff --name-only HEAD~1`).
   - Inline: the file the user is editing.
2. **Detect platform.**
   - Web: JSX with HTML elements, CSS / Tailwind / styled-components.
   - React Native / Expo: `View`, `Text`, `Pressable`, `expo-router`.
   - If ambiguous, ask.
3. **Detect existing direction.** Read theme tokens, the design-system entry
   point (`tailwind.config.*`, `theme.ts`, `tokens.json`), and at least two
   sibling components. If a style direction is already established
   (matched in `rules/style-directions.md`), name it and keep findings
   consistent with it. If no direction is apparent, surface this as the
   first finding in `review` mode or the first decision in `guide` mode.
4. **Read the code.** Do not review or generate code you have not read.

### Phase 2 — Load rules by mode

| Mode        | Always load                                                                                                  | Plus, when relevant                          |
| ----------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
| `guide`     | `rules/style-directions.md`, `rules/brand-identity.md`, `rules/visual-hierarchy.md`                          | `rules/color-systems.md` (any color decision), `rules/typography-pairing.md` (any text), `rules/signature-details.md` (always for polish pass). |
| `review`    | `rules/style-audit.md`, `rules/style-directions.md`                                                          | Same per-concern rules as `guide`.           |
| `direction` | `rules/style-directions.md`, `rules/brand-identity.md`, plus `templates/direction-brief.md` for output shape | `rules/color-systems.md`, `rules/typography-pairing.md` for the worked sketch. |

Do not pre-load all rules. The progressive-disclosure cost is real.

### Phase 3 — Compose with siblings

When the target overlaps another skill's domain, invoke it rather than
restating its rules.

| Code contains                                                  | Invoke                                                                                         |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Charts, graphs, dashboards, data-viz                           | `Skill("charting")` — chart type and library; keep this review focused on visual identity.    |
| Motion, transitions, hover-revealed state, scroll choreography | `Skill("animations")` — motion personality is a brand signal but the mechanics live there.    |
| New stories or visual-regression coverage                      | `Skill("storybook")` — scaffold a Playground story for the component under design.            |
| Foundational mechanics: contrast math, size minimums, dark-mode, icon consistency, ARIA | Defer to `/ux/rules/visual-design.md` + `/ux/rules/accessibility.md`. Do not re-derive. |

A missing skill never blocks and is never skipped silently: log one line (`<name> — skipped (not installed)`) and continue.

### Phase 4 — Output

#### `guide` mode

Produce a **build sheet** for the component:

```
## Visual Design: <Component>

**Style direction:** <name from style-directions.md, or "new — proposed">
**Platform:** Web | React Native | Cross-platform
**Rules applied:** [list]

### Tokens
- Color: <role table — surface, content, accent, semantic>
- Type:  <pairing — display / body / mono if any, with weights and sizes>
- Space: <scale base + the 4 values this component uses>
- Radius/border/shadow: <signature posture — values and rationale>

### Hierarchy
- Focal point: <what the eye should land on first, and the device used (size, weight, color, position)>
- Scan path: <2nd, 3rd, 4th stops>
- Breathing room: <where padding does the heavy lifting>

### Signature details (the 5%)
- <Detail 1 — the thing that makes this component feel like *this brand* and not generic AI-app>
- <Detail 2>

### Code
```<lang>
<implementation — concrete, copy-pasteable, with the tokens applied>
```

### Defer to /ux
- Contrast pairs to verify: <list>
- Size minimums to verify: <list>
- Dark-mode posture: <one-liner pointing at /ux/rules/visual-design.md>
```

#### `review` mode

Use the same severity ladder as `/ux` (Critical / High / Medium / Low) so
the two skills produce mergeable reports. Findings cite **file:line**, the
**named principle** (e.g. "weak focal hierarchy", "palette role collision",
"generic shadow"), why it matters, and a concrete fix with code.

End with:

- **Style direction match:** <named direction, or "inconsistent — picks
  from N directions">
- **Generic-AI-app score:** see `rules/style-audit.md` — `low | medium | high`
- **Top 3 fixes:** highest-impact changes first

#### `direction` mode

Fill in `templates/direction-brief.md`. The brief proposes **one primary
direction** and **one runner-up**, each grounded in `rules/style-directions.md`,
with a worked color/type sketch and the brand voice → visual translation
rationale from `rules/brand-identity.md`.

---

## Key Principles (Quick Reference)

These are always in context. Detailed rules are in `rules/` files.

### What this skill owns

- **Style direction** — which named direction the component sits in.
- **Color system** — palette construction, role hierarchy, accent strategy.
- **Typography pairing** — voice, personality, pairing rules.
- **Visual hierarchy** — focal point, scan path, drama, restraint.
- **Signature details** — the 5% that turns a generic card into a
  Linear / Stripe / Notion / Vercel card.
- **Style audit** — "does this look generic AI-app?".

### What this skill defers

- **WCAG contrast math** → `/ux/rules/visual-design.md` + `/ux/rules/accessibility.md`.
- **Touch-target / hit-area minimums** → `/ux/rules/touch-and-interaction.md`.
- **Microcopy / UX writing** → `/ux/rules/ux-writing.md`.
- **Motion mechanics** → `/animations`.
- **Chart-type / data-viz library choice** → `/charting`.
- **Dark patterns** → `/ux/rules/dark-patterns.md` (Critical by default there).

### The single best question this skill asks

**"If you stripped the logo, would a regular user recognise this as your
product?"** If no, the signature details are weak — see
`rules/signature-details.md`.

---

## Behavioral Rules

1. **Name the direction.** Every recommendation should sit inside a named
   style direction from `rules/style-directions.md`. Mixing directions
   without intent is the #1 reason components look generic.
2. **Tokens, not magic numbers.** Recommend named tokens (`color.accent.500`,
   `space.4`) over raw values. If the project has no tokens, propose them.
3. **Restraint beats decoration.** When in doubt, remove. "Brutalist" is
   not "add more borders"; "minimal" is not "remove until broken". Each
   direction has a specific *restraint posture* in `rules/style-directions.md`.
4. **Acknowledge what's already good.** Reinforce signature details the
   project already uses well.
5. **Code-ready output.** Every recommendation includes the actual values
   (CSS, Tailwind classes, React Native styles), not prose.
6. **Composability awareness.** A button is part of a system. Recommend
   what makes *this* component great *and* coherent with siblings.
7. **Never invent a brand voice the project doesn't claim.** If the user
   hasn't named one, ask before writing it into the output.
8. **Defer foundational mechanics.** Do not re-derive WCAG, touch
   targets, or dark-mode color math — point at `/ux` and move on.