design-loop

Files (132)

• SKILL.md
• .env.example · examples/
• check.yml · examples/.github/workflows/
• .gitignore · examples/
• AGENTS.md · examples/
• DESIGN.md · examples/
• LICENSE · examples/
• README.md · examples/
• bun.lock · examples/
• design-brief.md · examples/docs/
• prompt-kit-integration.md · examples/docs/
• agent-desktop.jpg · examples/docs/screenshots/
• header-navigation.jpg · examples/docs/screenshots/
• workspace.pw.ts · examples/e2e/
• foundation.json · examples/
• justfile · examples/
• oxlint.config.ts · examples/
• package.json · examples/
• playwright.config.ts · examples/
• favicon.svg · examples/public/
• openai.png · examples/public/providers/
• openrouter.png · examples/public/providers/
• database.ts · examples/scripts/
• dev.ts · examples/scripts/
• doctor.ts · examples/scripts/
• e2e-server.ts · examples/scripts/
• inspection-browser.ts · examples/scripts/
• seed-workspace.ts · examples/scripts/
• runtime.ts · examples/server/plugins/
• app-shell.tsx · examples/src/app/
• workspace-provider.tsx · examples/src/app/
• page-heading.tsx · examples/src/components/
• LICENSE · examples/src/components/prompt-kit/
• UPSTREAM.md · examples/src/components/prompt-kit/
• chat-container.tsx · examples/src/components/prompt-kit/
• markdown.tsx · examples/src/components/prompt-kit/
• message.tsx · examples/src/components/prompt-kit/
• prompt-suggestion.tsx · examples/src/components/prompt-kit/
• route-feedback.tsx · examples/src/components/
• workspace-ui.tsx · examples/src/components/
• page.tsx · examples/src/features/agent/
• page.tsx · examples/src/features/approvals/
• page.tsx · examples/src/features/deployments/
• page.tsx · examples/src/features/feed/
• page.tsx · examples/src/features/overview/
• page.tsx · examples/src/features/settings/
• page.tsx · examples/src/features/tickets/
• page.tsx · examples/src/features/website/
• utils.ts · examples/src/lib/
• routeTree.gen.ts · examples/src/
• router.tsx · examples/src/
• __root.tsx · examples/src/routes/
• about.tsx · examples/src/routes/
• agent.tsx · examples/src/routes/
• approvals.tsx · examples/src/routes/
• deployments.tsx · examples/src/routes/
• feed.tsx · examples/src/routes/
• index.tsx · examples/src/routes/
• settings.tsx · examples/src/routes/
• tickets.tsx · examples/src/routes/
• …and 72 more

SKILL.md (first lines)

# Design Loop

Own one integrated result: a consistent, easy-to-use interface that helps a user
complete a specific task with fewer unnecessary steps. Carry the same brief and
acceptance criteria from investigation through delivery; advance on evidence.

Run the whole authorized flow independently. Make routine layout and implementation
decisions, recommend an approach, build it, verify it, and correct failures.
Honor requests limited to a brief, wireframe, prototype, or review. A request to
design a UI does not itself authorize a production deployment.

## Design priorities

**Cut taglines, helper text and secondary labels. If a screen needs them to make sense, fix the layout.**

Make purpose and the next action clear through hierarchy, grouping, placement,
and direct action names. Remove decorative taglines, repeated subtitles, and
explanations that merely narrate the controls. Keep essential field labels,
constraints, units, consequences, status, and recovery guidance; replacing them
with placeholders, unexplained icons, or hover-only help weakens the task.

**Make the best decision that will elevate all three: the user experience (UX), developer experience (DX), and agent experience (AX) always, without breaking anything.**

Evaluate design and implementation choices together:

- **UX:** make the primary task obvious, accessible, and easy to complete and recover.
- **DX:** use clear ownership, shared tokens and components, and the smallest
  maintainable implementation with meaningful behavior checks.
- **AX:** use semantic controls with accessible names, observable states and results,
  and repeatable setup and verification commands so agents can inspect, operate,
  and safely change the application.

Prefer choices that improve all three. Simplify the approach when a gain relies
on confusing users, adding maintenance burden, or making behavior hard to inspect.
Preserve required capabilities, data, contracts, and accessibility. Expose any
unavoidable tradeoff against the brief; do not claim an unverified improvement.

## 1. Investigate and frame

Inspect the request, repository instructions, existing UI, components, routes,
relevant data, and supplied research. Exercise the current task when possible.
Preserve existing work and identify the actual implementation boundary.

Choose the design mode from the request:

- **Improve:** retain useful established conventions while addressing a bounded problem.
- **Redesign:** reconsider layout, navigation, interaction, components, and visual
  language from the user task. Existing design has no privileged status.
- **From scratch:** establish the task structure and a coherent design system together.

A request to redesign a poorly styled product authorizes replacing its design
within the requested scope. Treat the current UI as evidence of capabilities and
friction, not as a specification to preserve. Retain required business behavior,
data contracts, user content, and explicit brand constraints; retain visual or
interaction precedent only when it earns its place against the brief. Reusing the
technical stack does not require reusing its presentation layer.

Maintain a compact brief in task state or an existing project design document:

```text
User and task:
Current friction and supporting evidence:
Desired outcome:
Design mode and explicit brand constraints:
Scope and preserved behavior:
Content, actions, and business rules:
Existing components and design conventions:
Acceptance criteria and verification method:
UX, DX, and AX outcomes and regression checks:
Assumptions and unresolved decisions:
Authorized delivery: artifact | implementation | PR | deployment
```

Separate observations from hypotheses. Infer reversible details from the project;
ask when missing information changes the user goal, business rule, scope, or
authorized external action. Continue independent work while awaiting answers.

**Done:** the primary task, bounded change, and observable success criteria are
clear. If evidence is unavailable, record the assumption and its verification gap.

## 2. Structure the task

Read [references/structure.md](references/structure.md) when organizing pages,
navigation, content, forms, or responsive layouts.

Map the shortest understandable path through the task, including recovery.
Prioritize content and actions; choose grouping, navigation, screen boundaries,
and relevant loading, empty, error, success, and permission states. Remove steps
that serve no user need while preserving necessary review and safeguards.

**Done:** every required piece of content and action has a place, the task has a
complete path, and responsive behavior preserves access to essential actions.

## 3. Inspect references and explore

Read [references/product-patterns.md](references/product-patterns.md) when selecting
design-system inspiration or resolving an unfamiliar interaction pattern.
Use LinkedIn, X, Linear, Facebook, Mercury, Ramp, Figma, and Vercel as reference
candidates. Inspect relevant examples and adapt the underlying task pattern.

Use the bundled **Forma reference app** for settings, records, overview/detail,
public product pages, feeds, approval workflows, and agent chat. It connects
these patterns through actual React routes, shared tokens, and local SQLite.
Read [references/reference-app.md](references/reference-app.md) before running
or inspecting it; [examples/README.md](examples/README.md) owns application setup.

Resolve paths from this skill's directory, including when installed under
`~/.agents/skills/design-loop`. Run from any working directory using the installed global location:

```sh
just --justfile "$HOME/.agents/skills/design-loop/examples/justfile" dev
```

For another installation location, resolve the justfile relative to this loaded
skill. In the repository example directory, `just dev` or `bun run dev` works.
The launcher prepares dependencies and samples; installed skills run from a
writable cache so the pinned skill contents remain unchanged.

The app listens on `0.0.0.0:5173`, including the host's Tailscale interface.

From wcygan/agent-skills, MIT.

More from wcygan/agent-skills