agentleFS
CristhianzlCristhianzl/pocket-claude/.claude/skills/building-frontend-ui/SKILL.md

building-frontend-ui

Skill2 starsChanged 3 months agoMITView on GitHub

Build, refactor, and review frontend UI in any framework — components, accessibility, forms, client state and data fetching, responsive layout, performance, and client-side security/PII. Use whenever the task touches the UI layer: creating or changing a component, page, or screen; styling or theming; accessibility/a11y; forms; client state; responsive/mobile layout; or reviewing/refactoring frontend code. Use even when the user doesn't say "frontend" — if they mention a component, button, form, modal, page, screen, layout, CSS/Tailwind, ARIA, focus, or a UI bug, this applies. Not for pure backend/API/database work.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When concerns compete, resolve in this order.

    line 28
  2. Distinctive:

    Small, single responsibility, one component per file: If you describe it with "and"/"or", split it.

    line 45
  3. Distinctive:

    Composition over configuration: Prefer composing smaller pieces (children/slots, compound components) over a component with many flags.

    line 46
  4. Distinctive:

    Capture a learning: if you hit a convention/trap not in this skill.

    line 81

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Building Frontend UI

A frontend change is good when it reuses what already exists, is accessible by default, handles every state (loading, error, empty, long content), performs under real data, and leaks no data to the client. This skill is framework-agnostic: the workflow and rules live here; framework-specific mechanics live in references/<framework>.md and are loaded only when relevant.

Read first (always)

List learnings/ and read every file relevant to the current task — project conventions, the design system, banned dependencies, and component patterns live there and override the defaults in this file. If a learning conflicts with this skill, the learning wins — mention it.

Step 0 — Audit before you build (do not skip)

Most bad frontend work is net-new code that should have been reuse. Before writing anything:

  1. Find the design system. Grep for the token/theme source — CSS custom properties (--color-*, --space-*), a tailwind.config, a theme file, design-token JSON. Use those tokens; never hardcode raw hex, px spacing, or font sizes in a component.
  2. Find existing components and utilities. Grep/glob for a component that already does this (button, modal, field, table, empty-state) and reuse or extend it instead of creating a parallel one. Match the established prop and naming patterns.
  3. Find the i18n system, if any. Grep for a locales/ dir, i18n config, or translation calls (t(...), $t, useTranslation, FormattedMessage). If the project has one, every user-facing string goes through it — a hardcoded string in a translated app is a bug, and every new key must be added to all locale files (a key present in one language and missing in another ships broken UI).
  4. Read the surrounding files to copy the project's conventions (file layout, styling approach, state approach, test location).

→ verify: you can name the token source, the existing components you're reusing, the pattern you're following — and whether the project has i18n — or you've confirmed none exists.

Priority order

When concerns compete, resolve in this order. Each row points to its deep-dive reference.

#ConcernWhy it's ranked hereReference
1AccessibilityA broken experience for keyboard/AT users is a defect, not a polish itemreferences/accessibility.md
2Security & PII (client)Leaked tokens/PII and XSS are incidentsreferences/ + baseline CLAUDE.md
3Reuse & design tokensConsistency and maintainability start here (Step 0)this file
4Component designSmall, composable, single-responsibility unitsthis file
5State & dataWhere state lives decides everything downstreamreferences/state-and-data.md
6Forms & feedbackHighest-friction surface for real usersreferences/forms.md
7Responsive & layoutMobile-first; break by content, not devicereferences/responsive.md
8PerformanceReal data and real devices, not the happy pathreferences/performance.md
9Typography & UX writingClarity and polish that read as professionalreferences/ux-writing.md
10TestingBehavior, a11y, and visual — see the testing skillsskills/writing-tests

Component design (agnostic)

  • Small, single responsibility, one component per file. If you describe it with "and"/"or", split it.
  • Composition over configuration. Prefer composing smaller pieces (children/slots, compound components) over a component with many flags.
  • No boolean-prop explosion. Five booleans = 32 states, most invalid. Replace mode flags with explicit variant components so invalid combinations can't exist.
  • Children/slots over render callbacks unless the parent must pass data back (then use a scoped slot / render prop deliberately).
  • Never define a component inside another component — it remounts every render and breaks identity.
  • Type the public surface. Props and state are fully typed; no any. Stable keys for lists (never the array index when items reorder).
  • Specify a component as Variants × Sizes × States. Cover every state — default, hover, focus, active, disabled, loading — and resolve overlaps in that priority (disabled > loading > active > focus > hover > default).

State & data (agnostic)

  • Keep fetching out of leaf components. Data ownership lives in a provider/store/loader the UI consumes through an interface — agnostic to useState, a store, signals, or a server loader.
  • Derive, don't duplicate. Compute from existing state during render instead of storing a copy and syncing it.
  • Lift state only when shared; otherwise colocate it next to where it's used.
  • The URL is state. Filters, tabs, pagination, and expanded panels belong in query params so they're shareable and survive reload.
  • Always handle loading, error, and empty as first-class states. Details: references/state-and-data.md.

Accessibility floor (every change)

Semantic HTML before ARIA. <button> for actions, <a> for navigation — never a clickable <div>. Visible keyboard focus (never remove the outline without replacing it). Labels on every control; alt text on meaningful images (alt="" for decorative); aria-label on icon-only buttons. Honor prefers-reduced-motion. Fixability rule: apply mechanical fixes directly; for contextual/visual ones (real alt text, copy, color choices) leave a clear TODO — never invent alt text, labels, or content. Full checklist: references/accessibility.md.

Security & PII on the client

  • No tokens or secrets in localStorage/sessionStorage — prefer httpOnly cookies. Store only what the UI needs, versioned, in a try/catch.
  • Never render untrusted HTML (dangerouslySetInnerHTML/innerHTML) without sanitizing.
  • Minimize PII sent to the client, serialized into props/markup, or logged to analytics. Treat the client↔server boundary as a trust boundary.
  • No console.log in production. (These align with, and are partly enforced by, the baseline CLAUDE.md and hooks.)

Workflow

  1. Audit first (Step 0) — tokens, existing components, conventions.
  2. Design the component tree — name the pieces, pick variants over flags, decide where state lives.
  3. Build with semantic, accessible markup and the project's tokens. Handle loading/error/empty/long-content from the start.
  4. Wire state and data at the right level; keep fetching out of leaves; reflect navigable state in the URL.
  5. Make it responsive mobile-first; verify the layout at small/medium/large.
  6. Check performance on realistic data (lists, images, animation).
  7. Test behavior + accessibility (delegate to skills/writing-tests); add a visual check if the project has one.
  8. Capture a learning if you hit a convention/trap not in this skill.

Pre-delivery checklist

  • Reused existing components/tokens; no hardcoded hex/spacing/font sizes.
  • Keyboard-operable; visible focus; semantic elements; labels/alt present (or TODO for contextual ones).
  • Loading, error, empty, and long-content states handled.
  • No tokens/secrets in web storage; no unsanitized HTML; no PII leaked to client/logs.
  • Typed props/state; small single-responsibility components; stable keys.
  • Responsive at the project's breakpoints; animations honor reduced-motion.
  • If the project has i18n: no hardcoded user-facing strings; every new key present in all locale files.
  • Tests for behavior and accessibility; existing tests still pass.

See also

  • references/accessibility.md · references/state-and-data.md · references/forms.md · references/performance.md · references/responsive.md · references/ux-writing.md
  • Framework specifics: references/react.md · references/vue.md · references/svelte.md · references/web-components.md
  • skills/writing-tests (test strategy), skills/developing-features (general production-code rules, security depth), skills/reviewing-code (review output), rules/frontend.md (the enforced subset).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.