Kishi Design Architect

Kishi Design Architect

Use this skill as the default design brain for Codex. It turns UI work into a disciplined architecture process: brand DNA first, system constraints second, implementation third, verification last.

This skill is intentionally stricter than generic UI inspiration skills. It protects Kishi's projects from generic AI SaaS visuals, mismatched branding, weak hierarchy, inaccessible components, and pretty-but-fragile frontend code.

Activation Law

Invoke this skill for any task involving:

• Branding, visual identity, design direction, design systems, tokens, typography, color, iconography, imagery, or motion.
• UI/UX design, frontend visual design, component styling, layouts, responsive behavior, accessibility, or interaction states.
• React, Next.js, Tailwind, shadcn/ui, Magic UI, Lucide, forms, modals, navbars, cards, tables, charts, dashboards, pricing, landing pages, onboarding, checkout, or marketing sections.
• Phrases like "make it premium", "fix the UI", "polish this", "match the brand", "looks off", "frontend design", "UX", "more like Linear/Stripe/Vercel/Skool/Apple/DesignJoy", or "use our branding".

Do not invoke for pure backend, database, infrastructure, algorithm, terminal, or file-processing work unless there is a user-facing interface, visual output, or UX consequence.

Source Rules

Follow this priority order:

1. Explicit user request in current turn.
2. Closest project AGENTS.md.
3. Existing design docs, brand docs, tokens, CSS variables, Tailwind config, shadcn config, components, and page patterns.
4. This skill and its references.
5. External inspiration or generic best practices.

Never let a famous reference brand override the actual product identity.

Required Workflow

1. Inspect Before Taste

Before writing UI code or final design recommendations, inspect likely design sources:

• AGENTS.md, README.md, product/brand docs
• package.json
• tailwind.config.*, components.json, postcss.config.*
• app/globals.css, src/styles/**, styles/**
• app/layout.*, src/app/layout.*
• components/ui/**, src/components/ui/**
• existing pages or components similar to the target
• assets, logos, icons, screenshots, theme files

If a page needs visual confidence, render it with the browser when possible. Do not claim visual findings without rendered evidence.

2. Extract Brand DNA

Summarize the operating design system in a compact map:

Use references/brand-dna-protocol.md for brand-sensitive work.

3. Architect Screen Intent

Before implementation, know:

• User goal.
• Primary action.
• Screen hierarchy.
• Component inventory.
• State map.
• Responsive behavior.
• Accessibility requirements.
• Verification plan.

Keep this plan short unless the user asked for strategy.

4. Implement Inside Existing System

Use existing stack conventions first.

For React/Next/Tailwind:

• Prefer existing components/ui/** primitives.
• Use project cn() helper if present.
• Use cva only if already installed or established.
• Map repeated UI from typed arrays.
• Respect App Router client/server boundaries.
• Use semantic tags: main, section, header, nav, article, aside, footer, button, form, label, ul, li, table, th, td.
• Escape JSX text correctly.
• Keep exported props typed with interface; use type for unions.

Do not add new UI libraries or design frameworks without explicit need.

Kishi UI Law

These rules override generic inspiration:

• No purple gradients.
• No blur abuse.
• No decorative bokeh/orb/blob backgrounds.
• No heavy drop shadows unless existing brand justifies them.
• No transitions above 200ms.
• No transition-all.
• Animate transform and opacity only.
• No default Tailwind palette as design identity; use OKLCH/design tokens where available.
• No emoji as icons in landing copy or UI controls.
• No centered-everything layouts.
• No nested UI cards.
• No rounded text-pills where a standard icon/control is clearer.
• Cards default to 8px radius or less unless existing system says otherwise.
• Use Lucide icons when available.
• Use shadcn/ui base + Magic UI effects only when they fit the system.

Senior Design Rules

Hierarchy

Use size, weight, and color/opacity. Do not max out all three. Primary content must dominate; labels and secondary help text must support scanning without becoming invisible.

Spacing

Use a 4px baseline and existing spacing tokens. Avoid arbitrary values unless matching existing pixel-perfect assets. Related things sit closer together than unrelated things.

Typography

Use existing fonts. Body text needs readable line-height. Do not center long paragraphs. Do not uppercase long copy. Do not add letter spacing to body text.

Color

Use tokens and semantic colors. Avoid raw hex in components. Red is destructive/error, green is success, yellow/orange is warning, unless brand semantics already say otherwise.

Depth

Prefer borders and surface layers before shadows. One focal treatment per section. If glass/blur exists, support it with contrast, borders, and fallback surfaces.

Motion

Motion must explain feedback, state, or spatial relationship. Respect reduced motion. Hover must not shift layout dimensions.

Accessibility

Semantic HTML first. Every interactive element needs focus-visible state. Inputs need persistent labels. Errors need visible text and ARIA wiring. Icon-only buttons need aria-label. Touch targets need 44px minimum on mobile.

Component Contract

Every created or modified component needs:

• Semantic structure and heading hierarchy.
• Variants only when useful.
• Default, hover, active, focus-visible, disabled, loading, selected/current, empty/error states where relevant.
• Mobile-first responsive behavior.
• Light/dark support if project supports it.
• Accessible roles, labels, keyboard path, focus management.
• Stable dimensions for fixed-format controls.
• Data-driven rendering for repeated items.
• No random one-off CSS values.

Use references/component-state-matrix.md for detailed component rules.

Product Screen Patterns

Landing Pages

Sequence by buyer psychology:

1. Hero: what it is, who it is for, outcome, CTA, proof.
2. Problem: concrete friction.
3. Mechanism: why it works.
4. Benefits/features: outcomes, not generic features.
5. Proof: real proof only.
6. Offer/pricing: clear plan boundaries and recommended path.
7. Objection handling: FAQ, risk reversal, technical concerns.
8. Final CTA: one clear action.

Use references/ux-conversion-rulebook.md.

Dashboards

Optimize decision speed:

• Most important status first.
• Metrics include units, date range, trend, threshold, or comparison.
• Actions stay near affected objects.
• Tables use compact readable density.
• Empty/loading/error/stale/permission states are explicit.
• Avoid decorative charts that do not change decisions.

Forms

Reduce accidental friction:

• Visible labels.
• Correct input types/autocomplete.
• Inline validation on blur or submit.
• Error recovery path.
• Loading/disabled submit state.
• Desktop width constraints.

Anti-Pattern Gate

Before final response, audit against:

• references/ai-antipattern-audit.md
• references/ui-rulebook.md
• references/component-state-matrix.md
• references/ux-conversion-rulebook.md

When code changed, run the heuristic script if Node is available:

node ~/.agents/skills/kishi-design-architect/scripts/audit-ui-antipatterns.mjs app src components pages

Fix hard failures before declaring completion.

Output Shape

When implementing:

1. Files changed.
2. Design decisions.
3. Accessibility/state coverage.
4. Verification run.
5. Remaining gaps.

When only planning/auditing:

**Brand DNA**
| Layer | Finding | Rule |
|---|---|---|

**UI/UX Plan**
| Area | Decision | Reason |
|---|---|---|

**Risks**
| Risk | Fix |
|---|---|

Keep final answers concise. Let implementation and verification carry the weight.