AGENT SKILL

app-design

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.

适用职业设计师
使用场景视觉设计
License 许可
MIT
所属仓库
microsoft/rayfin
最近更新
2026-11-12
Stars
★ 662
Forks
77

01 前言 Front Matter

name
app-design
description
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.

02 资源文件 4

03 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 packages/frontend/index.html, then update the font family tokens in the @theme block of global.css.

Theming Workflow

Start by customizing packages/frontend/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.

Establish a runnable shell early

Once the source and capabilities are selected, replace the starter/welcome view with an authenticated shell before exhaustive query discovery is complete. Keep the dynamic auth provider and gate intact so both standalone and embedded users sign in before reaching app content. Build the title, navigation, layout, final content regions, responsive behavior, and visual direction with loading states in the places where live content will appear.

The shell must stay honest. Do not display invented figures, synthetic completion, or source-backed labels that have not been verified. As each real query or operation is validated, integrate its exact result shape into the corresponding region.

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:

State What to show
Loading A skeleton matching the expected content, or a calm connecting state for a documented transient backend condition
Empty A centered muted message explaining no data is available
Error An actionable, sanitized error that does not expose provider internals

Do not leave authentication, permission, configuration, or query errors in loading. Retry only a known transient condition, use a bounded attempt count, and transition to the error state if it persists.

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 packages/frontend/src/global.css using @theme. Use Tailwind classes directly in JSX.
  • Theming: Light/dark color tokens defined in packages/frontend/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 packages/frontend/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 packages/frontend/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.

04 同仓库更多 Skills

microsoft
microsoft/rayfin

rayfin-getting-started

Use when starting or creating a NEW Rayfin app, or when a Rayfin task comes up and you are not yet inside a Rayfin project. Gets you into a project with the Rayfin CLI, then hands off to the authoritative, version-locked in-project rayfin skill/docs that own all in-project work. Triggers: build a Rayfin app, start a Rayfin project, create a new Rayfin app, create-rayfin, npm create @microsoft/rayfin, rayfin init, scaffold rayfin, rayfin CLI, rayfin template, universal app, awesome-rayfin gallery, get started with Rayfin

★ 662
microsoft
microsoft/rayfin

visuals

Use when user wants to incorporate charts, graphs, data grid, or other visual representations of data into their project. Use VegaVisual and DataGrid components to create these visuals, utilizing the shared DataTable input, formatting, theme, and interactivity. Covers the onInteraction selection/click events host apps consume, named multi-table data input for layered overlays and reference lines, and Vega-Lite native selections. Triggers: chart, graph, plot, dashboard, KPI, metric, trend, scorecard, data grid, visualize.

数据分析师分析与可视化
★ 662
microsoft
microsoft/rayfin

schema-discovery

Explore Power BI semantic model schemas using DAX INFO functions. Progressive metadata discovery strategy, scope estimation, and narrowing techniques for tables, columns, measures, and relationships.

★ 662
microsoft
microsoft/rayfin

query-design

Separates DAX data-fetching from TypeScript presentation. Guides when to use DAX vs. TypeScript vs. Vega-Lite for aggregation, total rows, FORMAT(), SELECTCOLUMNS, BLANK handling, filtering, multi-grain queries, cross-filtering and cross-highlight subset/overlay queries, and format strings.

设计师演示文稿视觉设计
★ 662
microsoft
microsoft/rayfin

functions-capability

Apply and build the Universal App functions capability. Use for trusted server-side logic, secrets, external APIs, custom model endpoints, published Fabric data agents, webhooks, or privileged operations.

★ 662
microsoft
microsoft/rayfin

fabric-sdk

How to query Fabric data from a running app through the Rayfin connectors client. Use getRayfinClient().connectors.<name>.executeQuery to run DAX against a semantic model, and toQueryResult to normalize the response.

★ 662