npx claudepluginhub howells/arc --plugin arcThis skill uses the workspace's default tool permissions.
<tool_restrictions>
Provides Ktor server patterns for routing DSL, plugins (auth, CORS, serialization), Koin DI, WebSockets, services, and testApplication testing.
Conducts multi-source web research with firecrawl and exa MCPs: searches, scrapes pages, synthesizes cited reports. For deep dives, competitive analysis, tech evaluations, or due diligence.
Provides demand forecasting, safety stock optimization, replenishment planning, and promotional lift estimation for multi-location retailers managing 300-800 SKUs.
<tool_restrictions>
EnterPlanMode — BANNED. Do NOT call this tool. This skill has its own multi-phase design process. Execute the phases below directly.ExitPlanMode — BANNED. You are never in plan mode.
</tool_restrictions><arc_runtime>
This workflow requires the full Arc bundle, not a prompts-only install.
Resolve the Arc install root from this skill's location and refer to it as ${ARC_ROOT}.
Use ${ARC_ROOT}/... for Arc-owned files such as references/, disciplines/, agents/, templates/, and scripts/.
Use project-local paths such as .ruler/ or rules/ for the user's repository.
</arc_runtime>
Create distinctive, non-generic UI. Avoids AI slop (purple gradients, cookie-cutter layouts).
Announce at start: "I'm using the design skill to create distinctive, non-generic UI."
Arc UI design assumes Tailwind is the implementation target.
@theme tokens plus utility classesui-builder can implement with Tailwind classesarc:design:designer agent — design creation happens through this skillarc:review:designer exists but is for REVIEWING implementations AFTER they're built, not for creating designsThis skill works with these agents (reuse, don't duplicate):
| Agent | Location | When to Use |
|---|---|---|
ui-builder | ${ARC_ROOT}/agents/build/ | Build UI from the change spec you create |
figma-builder | ${ARC_ROOT}/agents/build/ | Build UI when Figma URL is provided |
design-specifier | ${ARC_ROOT}/agents/build/ | Quick design decisions during implement (empty states, dropdowns) |
designer | ${ARC_ROOT}/agents/review/ | Review implemented UI for AI slop |
Workflow:
/arc:design (this skill)
↓ creates change spec
ui-builder or figma-builder (builds it)
↓ implements
designer (reviews for AI slop)
Decide which path applies before loading the heavy reference set.
Design mode (default):
Polish mode:
Component fast-path:
Announce the chosen mode before continuing.
In full design mode, read the full reference set below. The component fast-path overrides this and loads only the relevant targeted rules.
In full design mode, you MUST read these files before proceeding.
<required_reading> Read ALL of these using the Read tool:
${ARC_ROOT}/references/frontend-design.md — UI fonts, anti-patterns, design review checklist. Critical.${ARC_ROOT}/references/brand-identity.md — Brand typography, color psychology, visual character (if no brand-system.md exists)${ARC_ROOT}/references/design-philosophy.md — Timeless principles from Refactoring UI${ARC_ROOT}/references/ux-laws.md — Psychology-based design principles: Fitts's, Hick's, Gestalt, Jakob's Law, Doherty Threshold${ARC_ROOT}/references/typography-opentype.md — OpenType features, tracking, text-wrap, fluid sizing${ARC_ROOT}/references/ascii-ui-patterns.md — Wireframe syntax and patterns${ARC_ROOT}/references/wiretext.md — When to use WireText vs ASCII vs browser review${ARC_ROOT}/references/tailwind-v4.md — Tailwind v4 syntax and token patternsThen load interface rules:
9. rules/interface/index.md — Interface rules index
10. rules/interface/tailwind-authoring.md — Tailwind class-level discipline
11. rules/interface/buttons.md — Button sizing and hierarchy
12. rules/interface/surfaces.md — Surface hierarchy and card usage
13. rules/interface/sections.md — Page section composition
And relevant domain rules based on what you're designing:
rules/interface/design.md — Visual principlesrules/interface/colors.md — Color palettes, OKLCH, tinted neutralsrules/interface/spacing.md — Spacing system, container queriesrules/interface/typography.md — Typography rules, OpenType featuresrules/interface/layout.md — Layout patterns, z-indexrules/interface/responsive.md — Responsive design, input detectionrules/interface/animation.md — If motion is involvedrules/interface/forms.md — If designing formsrules/interface/interactions.md — Interactive states, popover APIrules/interface/marketing.md — If designing marketing pagesrules/interface/app-ui.md — If designing app UI (dashboards, settings, data views)
</required_reading>Check for docs/brand-system.md first, then docs/design-context.md.
If brand-system.md exists (created by /arc:brand), load it — this is the canonical source for palette, typography, tone, and visual character. Do not re-ask brand questions. Inherit all identity decisions and focus this skill on feature-level UI design.
If only design-context.md exists, load it — this file contains project-wide aesthetic decisions (brand colors, chosen fonts, spacing scale, tone) that all design work should inherit. Do not re-ask questions that are already answered in design-context.md. Skip to Phase 1 for any established decisions.
If it does NOT exist, offer to create one:
Use the AskUserQuestion interaction pattern:
Question: "No project-wide design context found. Want to establish one? This saves brand decisions (colors, fonts, tone) so every future design session inherits them."
Header: "Design context"
Options:
1. "Yes, establish context" (Recommended) — Create docs/design-context.md with persistent aesthetic decisions
2. "No, one-off design" — Proceed without persistent context
If creating context, gather and save to docs/design-context.md:
# Design Context
Persistent aesthetic decisions for this project. All design work inherits these choices.
## Brand
- **Name**: [project name]
- **Personality**: [e.g., confident and technical, warm and approachable]
- **Tone**: [chosen from tone options]
## Typography
- **Display font**: [specific font]
- **Body font**: [specific font]
- **Mono font**: [specific font, if applicable]
## Color Palette (Tailwind @theme)
```css
@theme {
--color-brand-500: oklch(... ... ...);
/* Full shade scale */
--color-gray-500: oklch(... ... ...);
/* Tinted neutral scale */
}
After creating, proceed to Phase 1.
<progress_context>
**Use Read tool:** `docs/arc/progress.md` (first 50 lines)
Check for related prior design work and aesthetic decisions.
</progress_context>
**Internal consistency rule:** if any later design choice conflicts with the stored design context, brand system, or interface rules, resolve that conflict before moving on. Do not let the spec say one thing and the implementation guidance imply another.
---
## Phase 0.5: Component Fast-Path
If the request is for a single component rather than a page or product flow:
- Load only the 2-3 relevant rules files for that component type
- Skip visual reconnaissance unless the component already exists and is being redesigned
- Skip external inspiration research
- Compress direction gathering to 1-2 questions
- Continue with wireframe -> spec -> critique -> handoff as normal
## Phase 1: Visual Reconnaissance
**Before designing anything, see what exists.**
### If Redesigning Existing UI:
**Prefer Chrome MCP to capture current state. If unavailable, use `agent-browser`. If neither is available, ask for screenshots or review the code directly.**
**Analyze the screenshot against the Design Review Checklist from frontend-design.md:**
- Does it have any Red Flags (AI slop indicators)?
- What's the current aesthetic direction (if any)?
- What's working? What's not?
**Report findings to user:** "Here's what I see in the current UI: [observations]. The main issues are: [problems]."
### If Designing From Scratch:
- Confirm dev server is running (or will be)
- Ask if there's any existing brand/style guide to reference
- Check if there are reference designs or inspiration URLs to screenshot
---
## Phase 1.5: Design Mode
**Before gathering direction, establish what kind of UI you're designing.**
**Use the AskUserQuestion interaction pattern:**
Question: "What are you designing?" Header: "Design mode" Options:
**After selection:**
- **Marketing** → Load `rules/interface/marketing.md` as mandatory reference
- **App UI** → Load `rules/interface/app-ui.md` as mandatory reference
This mode context informs all subsequent phases — questions, research sources, wireframe patterns, and checklist items adapt accordingly.
---
## Phase 2: Gather Direction
### Question 0: Exploration Mode (Conditional)
**Offer this option when circumstances allow:**
- New project with no established design system
- Homepage, landing page, or marketing site design
- User seems uncertain about direction
- Greenfield UI with creative freedom
**Do NOT offer when:**
- Strict brand guidelines exist
- Designing a small component or iteration
- User has already specified a clear direction
- Adding to an existing design system
**If circumstances allow, use the AskUserQuestion interaction pattern:**
Question: "Would you like me to create 5 vastly different design directions, each at its own route? This lets you compare radically different approaches before committing." Header: "Exploration" Options:
**If exploration mode is chosen:**
- Each route (/design-1, /design-2, etc.) gets a completely different aesthetic
- Vary: color palette, typography, layout structure, tone, spatial composition
- Don't just tweak—make them *unrecognizable* from each other
- Write a style definition brief for each direction before building it:
- Layout structure
- Typography character
- Color direction
- Spacing strategy
- Surface treatment
- Shape language
- Personality
- After building all 5, ask user which direction resonates
- Then proceed with full design doc for the chosen direction
---
Ask the remaining questions **one at a time**:
### Question 1: Tone
"What tone fits this UI?"
- Minimal, bold, playful, editorial, luxury, brutalist, retro, organic, industrial, art deco, soft/pastel
### Question 1.5: Mode-Specific Question
**If Marketing mode:**
"How does the page tell its story?"
- Hero → problem → solution → proof → CTA (classic)
- Immersive scroll narrative (one idea per viewport)
- Feature showcase (dense, scannable)
- Minimal single-screen (everything above the fold)
- Editorial long-form (article-like)
**If App UI mode:**
"How information-dense should this be?"
- Sparse — generous whitespace, one focus per screen (e.g., onboarding)
- Balanced — comfortable density, clear hierarchy (e.g., settings)
- Dense — lots of data visible at once (e.g., dashboard, table views)
### Question 2: Memorable Element
"What should be memorable about this?"
**If Marketing:** The animation? Typography drama? Layout surprise? Photography style? Scroll behavior?
**If App UI:** The navigation paradigm? Micro-interactions? Information density approach? Empty state creativity? Data visualization style?
### Question 3: Existing Constraints
"Any existing brand/style to match, or fresh start?"
### Question 4: Inspiration
"Any reference designs or inspiration?"
- If provided, **screenshot them immediately using Chrome MCP** for visual reference
### Question 5: UI Chrome
"Should this have standard website chrome (header, footer, navigation), or feel more like an app?"
Consider:
- **Standard website chrome** — Fixed header with logo/nav, footer with links. Good for content sites, marketing pages, multi-page experiences where users need to navigate.
- **App-like experience** — Minimal or no persistent chrome. Content takes full focus. Good for tools, dashboards, immersive experiences, single-purpose flows.
- **Hybrid** — Minimal header (maybe just a logo), no footer. Common for SaaS apps.
**The default shouldn't always be "header + footer".** If the experience is focused (a tool, a game, a single flow), standard chrome can feel clunky and distract from the core experience. Let the purpose guide the frame.
---
## Phase 3: Research Inspiration (Optional)
**Use WebFetch to explore curated design examples based on the chosen direction.**
This phase is optional but recommended when:
- Starting from scratch with no existing references
- The user wants to see examples matching their chosen tone
- You need concrete visual patterns to inform decisions
### Siteinspire (Website/Homepage Design)
Siteinspire curates high-quality website designs. Use WebFetch to explore based on the chosen tone:
WebFetch URL patterns by tone:
By page type:
**WebFetch prompt:** "List the website names, their URLs, and a brief description of their visual style. Focus on typography choices, color palettes, and layout patterns."
### Mobbin (UI/Mobile Design Patterns)
Mobbin collects UI patterns from real apps. Use for component and interaction inspiration:
WebFetch URL patterns:
By screen type:
**WebFetch prompt:** "List the apps shown and describe their UI patterns—navigation style, card layouts, typography hierarchy, and interaction patterns."
### Research Workflow
1. **Based on user's chosen tone**, fetch 1-2 relevant Siteinspire pages
2. **Based on what you're designing** (homepage, dashboard, form), fetch relevant Mobbin screens
3. **Summarize findings** to user: "I found these patterns that match your direction: [observations]"
4. **Ask:** "Any of these resonate? Should I explore a specific site further with Chrome MCP?"
### Deep Dive with Chrome MCP
If a specific example catches interest, use Chrome MCP for detailed inspection:
**Note:** WebFetch provides quick overview; Chrome MCP provides detailed visual inspection. Use both strategically.
---
## Phase 4: Make Concrete Visual Decisions
**Capture SPECIFIC visual decisions, not conceptual themes.**
<principle>
**Complexity Matching:** Design complexity should align with aesthetic vision. Maximalist designs warrant elaborate code and rich details. Minimalist designs require restraint and precision—every element must earn its place. Don't add flourishes to a minimal design; don't under-build a maximalist one.
</principle>
Apply knowledge from the loaded references to make these decisions:
### Typography Selection
Using the font recommendations from `frontend-design.md`:
- **Display font:** [specific font name]
- **Body font:** [specific font name]
- **Mono font (if needed):** [specific font name]
**Never use:** Roboto, Arial, system-ui defaults, Instrument Serif (AI slop)
### Color Palette
- **Define in Tailwind v4 `@theme` with OKLCH, not hex-only values**
- **Background token:** [e.g., `--color-gray-950: oklch(...)`]
- **Surface token:** [e.g., `--color-gray-900: oklch(...)`]
- **Text primary token:** [e.g., `--color-gray-50: oklch(...)`]
- **Text secondary token:** [e.g., `--color-gray-400: oklch(...)`]
- **Accent token:** [e.g., `--color-brand-500: oklch(...)`]
- **Accent hover token:** [e.g., `--color-brand-600: oklch(...)`]
**Never use:** Purple-to-blue gradients (AI cliché)
**Never use:** Hex-only palettes with no OKLCH/Tailwind token mapping
### Spacing System
Define the scale being used:
- **Base unit:** 4px or 8px
- **Common values:** 4, 8, 12, 16, 24, 32, 48, 64
- **Component padding:** [e.g., 16px default, 24px for cards]
- **Section spacing:** [e.g., 64px between major sections]
### Spatial Composition
Beyond basic layout, make deliberate choices about:
- **Asymmetry:** Not everything needs to be centered or perfectly balanced
- **Overlap:** Elements can break grid boundaries, bleed off edges, layer on top of each other
- **Unexpected layouts:** Break the "header → hero → 3-column features → footer" pattern
- **Negative space:** Generous whitespace creates breathing room and draws focus to what matters
**Ask:** "Where can the layout do something unexpected?"
### Motion Philosophy
- **Where animation is used:** [specific locations]
- **Animation style:** [e.g., ease-out for enters, springs for interactive]
- **Duration range:** [e.g., 150-300ms]
### UI System Snapshot
Capture the reusable system that implementation should preserve:
- **Depth model:** [borders-only / subtle shadows / layered surfaces]
- **Surface ladder:** [canvas → surface → raised → overlay]
- **Radius scale:** [e.g., 4px / 8px / 12px]
- **Control heights:** [e.g., 32px compact, 40px default, 48px prominent]
- **Primary button pattern:** [height, padding, radius, fill/border treatment, core Tailwind utility shape]
- **Card/panel pattern:** [padding, border/shadow, radius, core Tailwind utility shape]
- **Input/select pattern:** [height, padding, border/background treatment, core Tailwind utility shape]
---
## Phase 5: Wireframe
**Create a structural wireframe before any code.**
Prefer WireText MCP when available for low-fidelity wireframes. If WireText is unavailable, create ASCII wireframes using patterns from `ascii-ui-patterns.md`.
If WireText is used:
- save the editable URL in the design doc
- capture the exported wireframe text or a short structural summary
- treat it as the source of layout structure, not visual fidelity
┌─────────────────────────────────────┐ │ Logo [Search...] [Menu] │ ├─────────────────────────────────────┤ │ │ │ [Main Content Area] │ │ │ └─────────────────────────────────────┘
**Include:**
1. Primary layout structure
2. Key interactive elements
3. Mobile version if responsive
4. States: empty, loading, error (where relevant)
**If App UI mode:** You MUST include at least one state variant beyond the populated state (empty, loading, or error). App UI without state design is incomplete.
**Ask:** "Does this structure feel right before I continue?"
---
## Phase 5.5: Create Change Spec
**THIS IS CRITICAL.** Translate aesthetic direction into **specific, measurable changes**:
```markdown
## Change Spec
### Typography
| Element | Before | After | Rule Reference |
|---------|--------|-------|----------------|
| h1 | `text-2xl font-normal` | `text-5xl font-semibold tracking-tight` | typography.md: display hierarchy |
| body | `text-sm font-normal` | `text-base/7 font-normal` | typography.md: body readability |
### Colors
| Element | Before | After | Rule Reference |
|---------|--------|-------|----------------|
| background | `bg-white` | `bg-gray-50` backed by `--color-gray-50: oklch(...)` | colors.md: warmth |
| accent | none | `bg-brand-500 hover:bg-brand-600` backed by `--color-brand-500/600` | colors.md: accent strategy |
### Spacing
| Element | Before | After | Rule Reference |
|---------|--------|-------|----------------|
| section padding | p-4 (16px) | p-12 (48px) | spacing.md: generous whitespace |
### Layout
| Element | Before | After | Rule Reference |
|---------|--------|-------|----------------|
| hero | centered text | asymmetric split with image overlap | layout.md: break the grid |
### Motion (if applicable)
| Element | Before | After | Rule Reference |
|---------|--------|-------|----------------|
| page load | none | staggered fade-up, 50ms delay | animation.md: entrance sequence |
Rules for change specs:
Self-check:
If you're only changing padding values, STOP. That's not a redesign.
Create the design direction document at docs/arc/specs/design-[component-name].md:
# Design Direction: [Component/Page Name]
## Aesthetic Direction
- **Tone:** [chosen - e.g., "minimal", "bold", "editorial"]
- **Memorable element:** [specific - e.g., "oversized typography", "micro-interactions on hover"]
## Typography
- **Display:** [font name] — [where used]
- **Body:** [font name] — [where used]
- **Mono:** [font name] — [where used, if applicable]
## Color Palette
| Role | Value | Usage |
|------|-------|-------|
| Background | `--color-gray-950: oklch(...)` | Page background |
| Surface | `--color-gray-900: oklch(...)` | Cards, panels |
| Text primary | `--color-gray-50: oklch(...)` | Headings, body |
| Text secondary | `--color-gray-400: oklch(...)` | Labels, hints |
| Accent | `--color-brand-500: oklch(...)` | CTAs, links |
| Accent hover | `--color-brand-600: oklch(...)` | Hover states |
## Spacing
- Base unit: 4px
- Tailwind spacing scale: `p-4` / `p-6` / `p-8`, `gap-4` / `gap-6` / `gap-8`
- Section gaps: `gap-12` (tight), `gap-16` (normal), `gap-24` (generous)
## Motion
- Page transitions: fade, 200ms ease-out
- Interactive elements: spring (stiffness: 400, damping: 25)
- Hover states: 150ms ease-out
## Layout
### Desktop
[ASCII wireframe]
### Mobile
[ASCII wireframe]
## Implementation Notes
- [Any specific technical considerations]
- Tailwind-first implementation: express decisions as `@theme` tokens plus utilities
- [Component library preferences]
- [Animation library: CSS-only vs motion/react]
- Avoid bespoke CSS when utilities/tokens are sufficient; extract components before reaching for custom styling
## UI System Snapshot
### Tokens
| Token | Value | Usage |
|------|-------|-------|
| Depth model | borders-only | Global surface strategy |
| Surface ladder | canvas / panel / raised / overlay | Layering hierarchy |
| Radius scale | 4px / 8px / 12px | Controls, cards, dialogs |
| Control heights | 32px / 40px / 48px | Dense, default, prominent controls |
### Canonical Patterns
| Pattern | Spec | Usage |
|---------|------|-------|
| Primary button | `h-10 px-4 rounded-lg bg-brand-500 hover:bg-brand-600` | Main CTA |
| Default card | `rounded-xl border border-gray-200 p-5` | Content container |
| Input/select | `h-10 px-3 rounded-lg border border-gray-300` | Form controls |
| Dense data row | `h-11 px-3 tabular-nums border-b border-gray-200` | Tables/lists |
## Anti-Patterns to Avoid
- [Specific things NOT to do for this design]
## Complexity Guardrails
Keep implementation simple. Flag these during code review:
- Wrapper divs that add no styling, semantics, or layout purpose
- More than 3-4 levels of nesting for simple content
- Cards within cards (use spacing and dividers instead)
- More than 5 distinct font sizes (muddy hierarchy)
- More than 3 distinct colors plus neutrals (visual noise)
- Elements with 15+ Tailwind classes (simplify or extract)
- Arbitrary spacing values (p-[13px]) instead of scale values
- Decorative elements that don't aid comprehension
## Interactive States
Every interactive element must address all 8 states:
| State | Requirement |
|-------|-------------|
| Default | Base styling |
| Hover | Subtle feedback (gated to `hover:hover` for touch) |
| Focus | Visible ring for keyboard (`focus-visible:ring-2`) |
| Active | Press feedback (`active:scale-[0.97]`) |
| Disabled | Reduced opacity, no pointer events |
| Loading | Spinner or skeleton (`aria-busy`) |
| Error | Red border + message (`aria-invalid`) |
| Success | Confirmation feedback |
## Contrast Requirements
- Body text: 4.5:1 against background
- Large text (≥18px bold, ≥24px): 3:1
- UI components (borders, icons): 3:1
- No pure black on pure white
Before handoff, critique the draft like a design lead reviewing a first pass. Do this even if the wireframe and change spec already look coherent.
ui-builder implement this cleanly with Tailwind tokens/utilities, or did the spec drift into generic CSS language?If any answer is weak, revise the design doc before proceeding. Do not hand off a “correct enough” draft when the weakness is already visible in the spec.
Run the Design Review Checklist from frontend-design.md:
If any Red Flags are present, revise before proceeding.
Use the AskUserQuestion interaction pattern:
Question: "Design documented. What's next?"
Header: "Next step"
Options:
1. "Create detailed plan" (Recommended) — Run /arc:detail for task breakdown
2. "Save and stop" — Return to this later
IMPORTANT: Do NOT automatically invoke other skills.
/arc:detail to create implementation tasks."docs/arc/specs/design-[name].md. Return anytime."When implementing this design (via /arc:implement), use Chrome MCP continuously when available. Outside Claude Code, prefer agent-browser, then Playwright.
mcp__claude-in-chrome__computer action=screenshot
mcp__claude-in-chrome__resize_window width=375 height=812 # Mobile
mcp__claude-in-chrome__computer action=screenshot
mcp__claude-in-chrome__resize_window width=1440 height=900 # Desktop
mcp__claude-in-chrome__computer action=screenshot
Never commit UI code without visually verifying it looks correct.
From frontend-design.md:
🚫 Never use sparkles/stars to denote AI features. Overused, meaningless, dated.
🚫 Never propose conceptual themes with metaphors. No "Direction: Darkroom / Metaphor: Photo emerging from developer bath". Instead: "Use bg-gray-950 with text-gray-50 and restrained brand-600 accents backed by @theme tokens."
🚫 Never use these:
<arc_log>
After completing this skill, append to the activity log.
See: ${ARC_ROOT}/references/arc-log.md
Entry: /arc:design — [Component/page] design ([aesthetic direction])
</arc_log>
<success_criteria> Design is complete when:
@theme tokens in OKLCHmcp__claude-in-chrome__*) as the preferred rendered-page capture path in Claude CodeUse this when the request is to clean up UI code after implementation rather than create new visual direction.
classNamenpx @tailwindcss/cli canonicalize --helptailwind-authoring.mdDuring longer design sessions, post a one-line status update before each major phase so the user can follow the flow.