agentleFS
MicrosoftKnown publishermicrosoft/aitour27-BRK390-building-ai-applications-with-microsoft-databases-and-fabric/src/caldova-insights/.agents/skills/app-design/SKILL.md

app-design

Skill1 starsChanged 53 days agoMITView on GitHub

Use when building or modifying the app layout, creating UI components, or making any visual design decisions. Ensures consistency, accessibility, and a polished, unique app.

13 other projects use a version of this, 6 of them edited.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 10 are common, 1 is distinctive, and 3 are very specific to this project.

  • 10

    Common

    Most of the 9 edited versions we read keep these.

  • 1

    Distinctive

    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. Very specific:

    Start by customizing src/global.css — this is the single source of truth for the app's visual identity.

    line 27
  2. Very specific:

    Colors: Update the semantic color tokens (--color-primary, --color-background, --color-card, --color-border, etc.) in both the @theme block …

    line 29
  3. Common:

    Fonts: Update the font family tokens as described in the Typography section above.

    line 31
  4. Common:

    Selective overrides last: After the base theme is in place, inspect and adjust individual components that need to deviate — an …

    line 33
  5. Common:

    Keep these principles in mind:

    line 37
  6. Common:

    Use semantic color tokens so surfaces, text, and borders adapt correctly to light and dark mode.

    line 38
  7. Common:

    Keep spacing consistent — use the spacing tokens from the theme rather than arbitrary values.

    line 41
  8. Common:

    Ensure all interactive elements are keyboard-accessible with visible focus indicators and appropriate disabled states.

    line 42
  9. Common:

    Read these reference files — they include "Make it yours" prompts that tie back to the aesthetic direction above:

    line 44
  10. Common:

    If the user explicitly requests full-width charts, confirm the design choice before proceeding.

    line 69
  11. Common:

    Start mobile-first and scale up columns with responsive breakpoints.

    line 73
  12. Common:

    Every component that depends on async data should handle all three states:

    line 80
  13. Very specific:

    CSS class merging: Use cn() from @/lib/utils (powered by clsx + tailwind-merge) to conditionally combine Tailwind class names.

    line 98
  14. Distinctive:

    UI Components: Use Radix primitives with Tailwind CSS styling for all interactive elements — buttons, inputs, dialogs, menus, tabs, etc.

    line 100

“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “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

App Design

Your job is to build cohesive, distinctive apps — not just correct ones. Add character through intentional design decisions — typography pairing, color emphasis, spatial rhythm, and a clear visual point of view.

Aesthetic Direction

Before building anything, decide the app's tone in one word and its signature detail — the one thing someone notices first. These two choices guide every decision that follows. Pick a tone that is specific and bold, not safe or generic. Examples like editorial, geometric, organic, industrial, playful, or minimal are starting points — don't limit yourself to these. Invent a direction that fits the app's purpose.

Then match your execution to your direction — a maximalist direction needs layered effects and rich detail in the code; a minimalist direction needs precise spacing, restraint, and careful typography. Elegance comes from committing to the direction fully, not from adding more.

Typography

Pick fonts that set the app's character — this is one of the strongest signals of intentional design. At minimum choose a characterful --font-heading paired with a complementary --font-base, ideally from the same foundry or design family. Update --font-monospace and --font-numeric if necessary. Avoid generic defaults like Arial, Inter, or Roboto.

Load fonts via Google Fonts (or another CDN) as <link> tags in index.html, then update the font family tokens in the @theme block of global.css.

Theming Workflow

Start by customizing src/global.css — this is the single source of truth for the app's visual identity. Every component uses these tokens, so setting them first means the entire UI shifts together.

  1. Colors: Update the semantic color tokens (--color-primary, --color-background, --color-card, --color-border, etc.) in both the @theme block and the .dark override to match the aesthetic direction. The defaults are neutral blue/grey — make them yours.
  2. Radius: Adjust --radius (the base radius) and the radius scale to match the tone — sharp/geometric (lower values), soft/rounded (higher values), or pill-shaped (--radius-circular).
  3. Fonts: Update the font family tokens as described in the Typography section above.
  4. Then build components. Focus component-level styling on layout, spacing, and element-specific details — not re-specifying colors and radii that the tokens already handle.
  5. Selective overrides last. After the base theme is in place, inspect and adjust individual components that need to deviate — an accent-colored card border, a button with a unique hover effect, etc.

Keep these principles in mind:

  • Use semantic color tokens so surfaces, text, and borders adapt correctly to light and dark mode.
  • Maintain sufficient contrast between text and backgrounds.
  • The recommended minimum text size is text-200.
  • Keep spacing consistent — use the spacing tokens from the theme rather than arbitrary values.
  • Ensure all interactive elements are keyboard-accessible with visible focus indicators and appropriate disabled states.

Read these reference files — they include "Make it yours" prompts that tie back to the aesthetic direction above:

  • UI Style Recipes — per-element styling guidance for buttons, cards, inputs, dialogs, tabs, tooltips, tables, and more.
  • Visual Style Recipes — chart theming, Vega-Lite config, dark mode chart support, and mark-specific styling.

App Layout

These are good defaults for app structure. Adapt them to the specific app's needs.

Page Structure

  • The app layout should fill the viewport.
  • On wide screens, constrain the content width so it doesn't stretch uncomfortably. Use responsive breakpoints or multi-column layouts to make good use of available space.

Don't default to the same layout every time. The structure should serve the aesthetic direction — a sidebar + main content split, a full-width single column, a multi-panel master-detail, an asymmetric split, or something else entirely. These are starting points, not an exhaustive list. Invent a layout that fits the app's purpose and tone.

The header/toolbar is part of the design language — not every app needs a traditional fixed header. Consider alternatives: a floating command bar, a compact inline toolbar, a branded banner, a collapsible drawer, a minimal top-right action cluster, or no header at all if the content speaks for itself.

Container Sizing

VegaVisual and other content components fill their container — the container controls their dimensions. Without constraints, charts and content stretch to the full viewport width, which produces squished, unreadable visuals on wide screens.

  • Constrain the dashboard wrapper, not individual charts. Apply a max-width to the outermost content wrapper that holds the dashboard. This single constraint keeps the entire layout proportional on wide monitors. If the app lacks an outer wrapper, create one.
  • Do not constrain individual chart containers. Let the wrapper width plus grid columns determine each chart's size naturally.
  • If the user explicitly requests full-width charts, confirm the design choice before proceeding.

Dashboard Grid

  • Start mobile-first and scale up columns with responsive breakpoints.
  • Support mixed-size cards via span utilities.

Avoid uniform grids where every card is the same size — they look like a spreadsheet. Vary card spans to create visual hierarchy: a wide chart spanning two columns next to a tall narrow KPI panel, or a full-width table below a row of smaller cards. Let the data importance guide which elements get more space.

Loading, Empty & Error States

Every component that depends on async data should handle all three states:

StateWhat to show
LoadingA skeleton placeholder matching the shape of the expected content
EmptyA centered muted message explaining no data is available
ErrorA destructive-styled banner with the error message

Dark Mode

Include a light/dark mode toggle in the app header or toolbar. Use the useAppTheme hook from @/hooks/use-theme to read and toggle the theme.


Coding Conventions

  • Styling: Tailwind CSS v4 utility classes for all styling. Theme colors are defined as CSS custom properties in src/global.css using @theme. Use Tailwind classes directly in JSX.
  • Theming: Light/dark color tokens defined in src/global.css via CSS custom properties. Dark mode uses the .dark class on the root html element, auto-detected via prefers-color-scheme, data-appearance attribute, or .dark class. The useAppTheme hook in src/hooks/use-theme.ts manages the toggle.
  • CSS class merging: Use cn() from @/lib/utils (powered by clsx + tailwind-merge) to conditionally combine Tailwind class names.
  • Icons: Lucide React for UI icons.
  • UI Components: Use Radix primitives with Tailwind CSS styling for all interactive elements — buttons, inputs, dialogs, menus, tabs, etc.

UI Token Rules

All styling must use the design tokens defined in src/global.css via Tailwind utility classes. Never hardcode raw color values, pixel sizes, or font stacks — raw values are only permitted in global.css where the tokens are defined. Refer to global.css for available tokens, their values, and expected usage.

Examples:

  • bg-primary text-primary-foreground — not bg-blue-600 text-white
  • text-300 — not text-sm or text-[14px]
  • p-400 gap-300 — not p-4 or gap-3
  • font-semibold — not font-[600]
  • rounded-xl — not rounded-[8px]
  • icon-size-200 — not w-4 h-4

cn() and tailwind-merge conflicts: tailwind-merge treats text-* utilities as one conflict group. In cn(), combining text size and text color with ambiguous text-* classes can drop one class. Prefer explicit length syntax for font size (e.g., text-[length:var(--text-300)]) when combining with text color classes inside cn(). If classes are static and not merged, text-300 text-foreground is acceptable.

Form element font inheritance: Native form controls may not inherit the page font family by default. Ensure base styles in global.css set font-family: inherit for select, input, textarea, and button.


Final Audit

After assembling a layout, audit each element in its actual context — not in isolation. A component may look correct on its own but break the visual rhythm of the page. Check: Is every text legible? Are labels proportional to their controls? Are toolbar rows aligned on a shared edge? Do charts fill their containers? Do repeated elements (badges in tables, icons in lists) maintain appropriate visual weight for their density? Fix anything that fails.

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.