跳到主内容
智客 ZICQ

技能库 智客分类:设计创意 frontend-style-guide

Frontend Style Guide

在研究 React 组件或样式前端代码时应用 Lightdash 前端样式指南和设计原理. 用于编辑TSX文件,构建或审查UI,修饰造型问题,或用户提及曼汀,设计,造型,或CSS模块时.

380 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

在研究 React 组件或样式前端代码时应用 Lightdash 前端样式指南和设计原则

何时用

编辑 TSX 文件, 构建或审查 UI, 固定样式问题, 或当用户提及 Maintine, 设计, 样式, 或 CSS 模块

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Lightdash Frontend Style Guide、Mantine 8、Design principles、Component Checklist、Styling Best Practices、Core Principle: Theme First。

文件分析

文件分析:这是一份仅含 SKILL.md 的指令型技能,代理激活后整份正文进入上下文。

官方 description(原文)

Apply the Lightdash frontend style guide and design principles when working on React components or styling frontend code. Use when editing TSX files, building or reviewing UI, fixing styling issues, or when the user mentions Mantine, design, styling, or CSS modules.

Lightdash Frontend Style GuideMantine 8Design principlesComponent ChecklistStyling Best PracticesCore Principle: Theme FirstStyling HierarchyNEVER UseTheme Extensions (For Repeated Patterns)Context-Specific OverridesColor GuidelinesNeutral tokens

· allowed-tools:Read, Edit, Write, Glob, Grep

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
frontend-style-guide
description
Apply the Lightdash frontend style guide and design principles when working on React components or styling frontend code. Use when editing TSX files, building or reviewing UI, fixing styling issues, or when the user mentions Mantine, design, styling, or CSS modules.
allowed-tools
Read, Edit, Write, Glob, Grep实验字段,支持情况取决于客户端;字段声明本身不会授予工具权限。
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「frontend-style-guide」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-26586535307f86bc-%E5%89%8D%E7%AB%AF%E6%A0%B7%E5%BC%8F%E6%8C%87%E5%8D%97.html
请存为 .cursor/skills/frontend-style-guide/SKILL.md 或 .claude/skills/frontend-style-guide/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/lightdash/lightdash' --list

npx skills add 'https://github.com/lightdash/lightdash' --skill 'frontend-style-guide'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: frontend-style-guide metadata: internal: true description: Apply the Lightdash frontend style guide and design principles when working on React components or styling frontend code. Use when editing TSX files, building or reviewing UI, fixing styling issues, or when the user mentions Mantine, design, styling, or CSS modules. allowed-tools: Read, Edit, Write, Glob, Grep --- # Lightdash Frontend Style Guide Apply these rules when working on any frontend component in `packages/frontend/`. ## Mantine 8 The app runs on Mantine 8 (`@mantine/core`), with the theme in `src/theme/`. ## Design principles The theme is neutral and quiet, in the spirit of shadcn, Radix and Kumo: one ink accent, flat surfaces, soft borders, a tight type scale. Most of what "looks right" comes from using the defaults. Check each rule before you add a colour, a shadow or a size. 1. **One accent, and it is ink.** The primary action on a surface is the theme primary (near-black in light, near-white in dark). Never colour a Button or ActionIcon `blue`, `dark`, `indigo` or `ldDark` for emphasis. Colour on a control means state: `red` destructive, `yellow` warning, `teal` "copied", `orange` favourite, `green` only for the existing verify/merge actions. Indigo belongs to AI surfaces. Links are the only blue text. 2. **Hierarchy comes from variant, not colour.** `filled` is the one primary action per card, header or modal footer. `default` (bordered) is secondary. `light` is a tertiary or toggle-like action ("Add filter"). `subtle` is for icon buttons and inline actions; it is the ActionIcon default. If a surface has two filled buttons, one of them is wrong. 3. **Surfaces are flat.** Paper and Card are bordered with no shadow and a 12px radius by default; shadows only on floating layers (Menu and Popover `md`, Modal `lg`). Do not pass `withBorder`, `shadow` or `radius` to restate that. Empty or placeholder sections use ``. 4. **Neutrals are tokens, never hand-picked pairs.** `--mantine-color-body` (surface), `--ld-color-page` (canvas), `default-border`, `default-hover`, `text`, `dimmed`, `placeholder`. `ldGray.N` already resolves per scheme (0 canvas, 1 muted fill, 2 border, 3 strong border, 5 tertiary text, 6 = dimmed, 7 label, 9 text), so `light-dark(ldGray-x, ldDark-y)` and `@mixin dark` blocks for neutrals are always a smell. Secondary text is `c="dimmed"`. 5. **Type is a scale, not a slider.** Body is 14/20. Headings are 600 on `Title` orders 1 to 6 (28 to 14px); labels and table headers are 500; everything else 400. Use `fz="xs|sm|md"`, never `fz={13}`. Card and section titles are `Title order={5}`; page tops use `PageHeader`. 6. **Space on the token grid.** Card padding `md`, group gaps `xs`/`sm`, section gaps `lg`, page gutters `lg`/`xl`. No pixel margins; if a layout needs `margin-top: 20px` it is `mt="lg"`. 7. **Icons are quiet.** `MantineIcon` at stroke 1.5, 16px next to text and 14px in xs controls, coloured `dimmed` when they are secondary. Every icon-only button has an `aria-label` and a Tooltip. 8. **Inputs are calm.** Default variant, soft border, focus is a darker border with no ring. `size="xs"` controls carry compact secondary labels automatically. Selects mark the selected option with a check; filter value pickers are the standard combobox, not a custom list. 9. **Motion is functional.** Dropdowns pop from their anchor and modals fade, both from the theme. Nothing else animates unless it shows progress. 10. **Dark mode is designed, not derived.** Check both schemes before you finish. Never read `useMantineColorScheme` to pick a colour; use a token. Editors take `useEditorTheme()`; only JS consumers with no CSS (ECharts, Leaflet) read `useComputedColorScheme`. 11. **States are shared components.** `EmptyStateLoader` for loading, `InlineErrorState` for a failed section, `SuboptimalState` for a failed page, `` for "nothing here". 12. **Before writing CSS, look for the thing that already exists:** a variant, a token, an `ld-*` utility class, or a shared control (`CopyActionIcon`, `FavoriteActionIcon`, `ConfirmDeleteButton`, `TruncatedText`, `FilterFacet`, `NumberInput`, `MantineModal`). **Self-review before you hand a screen over:** open it in light and dark; count filled buttons per surface (max one); look for blue that is not a link; look for a shadow on a card; look for a font size or grey that is not a token; look for an icon button without a tooltip. The Explorer page is the reference surface when in doubt. ## Component Checklist When creating/updating components: - [ ] Use `@mantine/core` imports - [ ] No `style` or `styles` props - [ ] Check Mantine docs/types for available component props - [ ] Use inline-style component props for styling when available (and follow <=3 props rule) - [ ] Use CSS modules when component props aren't available or when more than 3 inline-style props are needed - [ ] Theme values ('md', 'lg', 'xl', or 'ldGray.1', 'ldGray.2', 'ldDark.1', 'ldDark.2', etc) instead of magic numbers - [ ] When using mantine colors in css modules, always use the theme awared variables: - `--mantine-color-${color}-text`: for text on filled background - `--mantine-color-${color}-filled`: for filled background (strong color) - `--mantine-color-${color}-filled-hover`: for filled background on hover - `--mantine-color-${color}-light`: for light background - `--mantine-color-${color}-light-hover`: for light background on hover (light color) - `--mantine-color-${color}-light-color`: for text on light background - `--mantine-color-${color}-outline`: for outlines - `--mantine-color-${color}-outline-hover`: for outlines on hover ## Styling Best Practices ### Core Principle: Theme First **The goal is to use theme defaults whenever possible.** Style overrides should be the exception, not the rule. ### Styling Hierarchy 1. **Best**: No custom styles (use theme defaults and variants) 2. **Theme extension**: For repeated patterns, add a variant or rule in `src/theme/components/.module.css` (registered in `src/theme/components/index.ts`) 3. **Component props**: Simple overrides (1-3 props like `mt="xl" w={240}`) 4. **CSS modules**: Complex styling, more than 3 props, or a single rule Mantine has no prop for (`align-self`, `overflow`, `cursor`, `white-space`) as a role-named class in the file's module. `flex-shrink`/`flex-grow` are the `flex` style prop. No global utility classes. ### NEVER Use - `styles` prop (always use CSS modules instead) - `style` prop (inline styles) ### Theme Extensions (For Repeated Patterns) If you find yourself applying the same style override multiple times, put it in the theme. Each component has a CSS module in `src/theme/components/` and an entry in `src/theme/components/index.ts`: ```css /* src/theme/components/Badge.module.css */ .root[data-variant='light'] { text-transform: none; font-weight: 500; } ``` ```tsx // src/theme/components/index.ts Badge: Badge.extend({ defaultProps: { variant: 'light', color: 'gray' }, classNames: badgeClasses, }), ``` Reach for the `vars` callback only when Mantine writes the value inline (button and badge colours, NavLink fill, input font size), because CSS cannot override an inline custom property. ### Context-Specific Overrides #### Inline-style Component Props (1-3 simple props) ```tsx // ✅ Good Submit // ❌ Bad - Too many props, use CSS modules instead Submit ``` Common inline-style props: - Layout: `mt`, `mb`, `ml`, `mr`, `m`, `p`, `pt`, `pb`, `pl`, `pr` - Sizing: `w`, `h`, `maw`, `mah`, `miw`, `mih` - Colors: `c` (color), `bg` (background) - Font: `ff`, `fs`, `fw` - Text: `ta`, `lh` #### CSS Modules (complex styles or >3 props) Create a `.module.css` file in the same folder as the component: ```css /* Component.module.css */ .customCard { transition: transform 0.2s ease; cursor: pointer; } .customCard:hover { transform: translateY(-2px); box-shadow: var(--mantine-shadow-lg); } ``` ```tsx import styles from './Component.module.css'; {/* content */}; ``` **Do NOT include `.css.d.ts` files** - Vite handles this automatically. ## Color Guidelines **Prefer default component colors.** Buttons, ActionIcons and Badges get the right neutral or ink from the theme; a `color` prop on a control should only ever name a state (see Design principles). ```tsx // ❌ Bad - restates the theme, and is a near-black button in dark mode Apply // ✅ Good - the theme already renders these Apply // ❌ Bad - hand-picked grey Secondary text // ✅ Good - semantic token Secondary text ``` ### Neutral tokens | Token | Purpose | | ----- | ------- | | `--mantine-color-body` | Surface (cards, inputs, menus) | | `--ld-color-page` | Page canvas behind surfaces | | `--mantine-color-default-border` / `default-hover` | Borders and hover fills of neutral controls | | `--mantine-color-text` / `dimmed` / `placeholder` | Primary, secondary and tertiary text | | `ldGray.0-9` | Same role in both schemes: 0 canvas, 1 muted fill, 2 border, 3 strong border, 4 faint icon, 5 tertiary text, 6 dimmed, 7 label, 9 text | ### Dark Mode in CSS Modules Neutrals need no dark-mode branch: the tokens and `ldGray.N` already resolve per scheme. ```css /* ❌ Bad */ .row:hover { background-color: var(--mantine-color-ldGray-0); @mixin dark { background-color: var(--mantine-color-ldDark-5); } } /* ✅ Good */ .row:hover { background-color: var(--mantine-color-default-hover); } ``` Use `light-dark()` only for a non-neutral pair that has no token, such as an accent tint: ```css .highlight { background-color: light-dark( var(--mantine-color-indigo-0), var(--mantine-color-indigo-9) ); } ``` ## Always Use Theme Tokens ```tsx // ❌ Bad - Magic numbers // ✅ Good - Theme tokens ``` ## Remove Dead Styles Before moving styles to CSS modules, check if they're actually needed: ```tsx // ❌ Unnecessary - display: block has no effect on flex children Submit // ✅ Better - Remove the style entirely Submit ``` ## Shared Layout CSS Variables (heights, widths, z-indexes) Cross-cutting layout constants (navbar/header/banner/footer heights, page content widths, sidebar dimensions, dashboard header/tab heights and z-indexes) are exposed as **global CSS variables** so CSS modules can use them directly: ```css /* ✅ Reference the global var — resolves on :root everywhere */ .myPanel { top: var(--dashboard-header-height); max-width: var(--page-content-max-width-large); } ``` ```css /* ❌ Don't hardcode the literal — drifts from the source of truth */ .myPanel { top: 50px; } ``` ```tsx // ❌ Don't bridge a constant into CSS via an inline style object
``` **Source of truth:** the numeric values live in their `*/constants.ts` files (e.g. `components/common/Page/constants.ts`, `components/common/Dashboard/dashboard.constants.ts`) and are registered as CSS variables in **`src/theme/cssVariablesResolver.ts`** (wired into the Mantine provider via Mantine's `cssVariablesResolver`). Read that file for the full list of available `var(--...)` names before defining your own. **To add a new shared layout constant:** add the number to the relevant `constants.ts`, register it in `src/theme/cssVariablesResolver.ts`, then reference `var(--your-name)` in CSS. Don't re-declare the literal in a `.module.css` file and don't pass it through an inline `style`. Keep using the numeric constant directly in TS where you need it as a JS value (e.g. a Mantine `h=` prop). ## Theme-Aware Component Logic Do not read the colour scheme to pick a colour; pass a token and let CSS resolve it. The two legitimate readers are code editors and chart libraries that consume plain JS values: ```tsx // Monaco / Ace theme names const { monaco, ace } = useEditorTheme(); // ECharts, Leaflet and other non-CSS consumers const isDark = useComputedColorScheme('light') === 'dark'; ``` ## Use the clsx utility exported by @mantine/core ```tsx import { clsx } from '@mantine/core'; const MyComponent = () => { return (
My Component
); }; ``` ## Select/MultiSelect grouping ```tsx ``` ## Reusable Components ### Modals - **Always use `MantineModal`** from `components/common/MantineModal` - never use Mantine's Modal directly - See `stories/Modal.stories.tsx` for usage examples - For forms inside modals: use `id` on the form and `form="form-id"` on the submit button - For alerts inside modals: use `Callout` with variants `danger`, `warning`, `info` ### Shared controls - **Copy to clipboard**: `CopyActionIcon` from `components/common/CopyActionIcon` (`value`, optional `copyLabel`/`copiedLabel`/`icon`/`tooltipPosition`, plus ActionIcon props). Never hand-roll `CopyButton` + `ActionIcon` + icon swap. - **Favourite toggle**: `FavoriteActionIcon` from `components/common/FavoriteActionIcon` (`isFavorite`, `onToggle`, optional `name` for the label). - **Two-click delete**: `ConfirmDeleteButton` from `components/common/ConfirmDeleteButton` (`onConfirm`, `aria-label`, optional `tooltip`); arms on first click, fires on the second, disarms on blur or timeout. - **Faceted filters** (popover with search, counts, groups, select all): `FilterFacet` from `components/common/FilterFacet`. ### Callouts - Use `Callout` from `components/common/Callout` - Variants: `danger`, `warning`, `info` ### Empty / Unavailable Sections (dotted style) - **``** (also `Card`) renders a dashed border with a transparent background — the house style for empty, placeholder, or unavailable sections. Defined in `src/theme/components/Paper.module.css`; used by e.g. `FavoritesPanel` and `AiAgentKnowledgeFilesSection`. - **Section failed to load**: use `InlineErrorState` from `components/common/InlineErrorState` — a dotted Paper with a muted message and optional `onRetry` button. Keep it quiet; a failing secondary panel shouldn't shout. - **Placeholder values** (stat tiles etc. with no data): render an em dash (`—`) in `ldGray.5` inside a dotted container rather than fake zeros or endless skeletons. Skeletons mean "loading", dotted means "nothing here". - Reserve `ErrorState` / `SuboptimalState` for whole-page failures. ### Polymorphic Clickable Containers Use these when you need a layout container that is also clickable — avoids the native `` background/border reset problem. - **`PolymorphicGroupButton`** from `components/common/PolymorphicGroupButton` — a `Group` (flex row) that is polymorphic and sets `cursor: pointer`. Use for horizontal groups of elements that act as a single button. - **`PolymorphicPaperButton`** from `components/common/PolymorphicPaperButton` — a `Paper` (card surface) that is polymorphic and sets `cursor: pointer`. Use for card-like clickable surfaces. Both accept all props of their base component (`GroupProps` / `PaperProps`) plus a `component` prop for the underlying element. ```tsx // ✅ Clickable row without native button style bleed Label // ✅ Clickable card surface Card content // ❌ Avoid - native brings unwanted background/border in menus and panels ... ``` ### NumberInput - **Always use `NumberInput` from `components/common/NumberInput`** — never Mantine's NumberInput directly - Mantine 8's onChange emits `number | string` (empty field, half-typed values like `-`/`12.`, unsafe-large integers). The wrapper's `onNumberChange` shields you: it fires with a `number`, or `undefined` when the field is cleared — transient strings never fire - **Integer-only by default** — the wrapper defaults `decimalScale={0}` (most fields are ports, counts, timeouts). Decimal fields opt in with `decimalScale={2}` etc., or `decimalScale="unlimited"` to remove the cap - The raw `onChange` prop remains available only for `form.getInputProps()` spreads, where the form library owns parsing ```tsx // ✅ Good - cleared field maps to a domain decision at the call site setLimit(v ?? DEFAULT)} /> // ✅ Good - number-or-undefined sinks take the callback directly // ✅ OK - form spread owns value/onChange // ❌ Avoid - hand-rolled typeof guards on the raw Mantine component { if (typeof v === 'number') setX(v); }} /> ``` ### EmptyStateLoader - Use `EmptyStateLoader` from `components/common/EmptyStateLoader` for **any** centered loading state: page-level guards, panels, tables, empty containers - Built on `SuboptimalState` (Mantine v8) — renders a spinner with an optional title, fully centered in its parent ### TruncatedText - Use `TruncatedText` from `components/common/TruncatedText` whenever text may overflow a constrained width - Pass `maxWidth` (number or string) to control the truncation boundary - Automatically shows a tooltip with the full text **only when the text is actually truncated** (no tooltip spam for short names) - Defaults to `fz="sm"`; override via standard `Text` props ```tsx // ✅ Good - truncates long names, tooltip only appears when needed {item.name} // ✅ Accepts any Text prop {space.name} ``` ### Tables with search, pagination, and sorting Use the `ContentTable` component from `components/common/ContentTable` for tables with search, pagination, and sorting. If you need filters, use FilterFacet ## Mantine Documentation List of all components and links to their documentation in LLM-friendly format: `https://mantine.dev/llms.txt`

相关技能

设计创意

Automation Workflows

设计和实施自动化工作流程,以节省时间和规模化操作作为独家. 用于识别重复任务实现自动化,构建跨工具的工作流程,设置触发器和行动,或优化现有自动化. 包括自动化机会识别,工作流程设计,工具选择(Zapier,Make,n8n),测试,和维护. 触发"自动","自动","工作流程自动…

设计创意

Ui Ux Pro Max

UI/UX设计智能及建筑抛光接口实施指导. 当用户要求UI设计,UX流量,信息架构,视觉风格方向,设计系统/托盘,组件规格,副本/显微镜,可访问性,或生成/critique/refine前端UI(HTML/CSS/JS,React,Next.js,Vue,Svelte,Tailw…

设计创意

Frontend Design

创建美丽现代UI的专家前端设计指南. 在构建起落架页面,仪表板,或任何用户界面时使用.

设计创意

N8n Workflow Automation

设计和输出 n8n 工作流程 JSON 有强力触发器, idempotency, 错误处理, 记录, 重试, 以及 人入"一站"审查队列. 当您需要可审计的自动化时使用.