agentleFS
Sign inStart free
qlan-roqlan-ro/mainframe/.agents/skills/mainframe-design-system/SKILL.md

mainframe-design-system

Skill44 starsChanged 3 months agoMITView on GitHub

Use when building or restyling Mainframe UI components, or reviewing their design conformance. Follow the app's existing primitives and theme tokens.

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use source values rather than copying token tables.

    line 19
  2. Very specific:

    Use semantic tokens consistently for the same role.

    line 24
  3. Very specific:

    Use min-w-0 on shrinking flex children and min-h-0 on scrolling flex children.

    line 25
  4. Very specific:

    Check narrow widths, long labels, the relevant state matrix, light and dark themes, and compact UI scale (packages/ui/src/store/theme.ts).

    line 42

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

Mainframe design system

Mainframe uses React, Tailwind v4, and shadcn primitives in packages/ui/src.

Current sources

Consult the source relevant to the change:

  • packages/ui/src/components/ui/: shared primitives. Match a nearby feature's composition; extend a primitive when it needs another prop rather than bypassing it with raw Radix in a feature.
  • packages/ui/src/styles/globals.css: base theme, typography, radius, and Tailwind mappings.
  • packages/ui/src/styles/domain-tokens.css: domain colors and app chrome.
  • packages/ui/src/styles/app.css: stylesheet composition.

Use source values rather than copying token tables. A CSS variable only becomes a Tailwind utility when the theme maps it; check the mapping before using a domain token.

Component conventions

  • Reuse primitive variants and defaults. Put shared visual changes in the primitive or theme instead of repeating overrides across features.
  • Use semantic tokens consistently for the same role. Check other uses before changing a token: foreground also fills tooltip backgrounds.
  • Use min-w-0 on shrinking flex children and min-h-0 on scrolling flex children. Let the container bound panel height.
  • Give dialogs a visible exit. Follow the current DialogContent and DialogFooter APIs in components/ui/dialog.tsx.
  • Interactive elements have stable <surface>-<element> data-testids, keyed by domain id rather than array index; primitives pass them through.
  • Represent the actual data contract and relevant empty, loading, error, populated, disabled, and running states.

Status colours

Each status hue has one meaning; do not choose by appearance.

  • primary: selected, or running/wants attention (working spinner, "your turn" dot, unread dot, Run/Launch glyph).
  • success: connected, healthy, or done (daemon connection dot, healthy PR row, done check). Never "running".
  • warning: needs the user or degraded (Unattended chip, missing worktree/transcript, automation awaiting an answer).
  • destructive: failed, or an irreversible action (errors, delete/stop).

Verification

  • Render visual changes in the running app; mounting tests and typechecking do not establish visual conformance. Use computed styles or element bounds to resolve size, color, and alignment questions.
  • Check narrow widths, long labels, the relevant state matrix, light and dark themes, and compact UI scale (packages/ui/src/store/theme.ts).
  • For color-token changes, run pnpm --filter @qlan-ro/mainframe-ui exec vitest run src/styles/__tests__/contrast.test.ts.
  • Typecheck with pnpm --filter @qlan-ro/mainframe-ui typecheck.

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.

Check your setup, free