flow-tailwind-shadcn

Files (7)

• SKILL.md
• evals.json · evals/
• component-patterns.md · references/
• critique-protocol.md · references/
• design-craft.md · references/
• design-tokens.md · references/
• tailwind-v4.md · references/

SKILL.md (first lines)

# Goal

Implement accessible, keyboard-navigable, and responsive UI components using the project's Tailwind CSS v4 design
system and shadcn-svelte primitives. Every design choice should be intentional and explainable — not the default
output another AI would produce.

# When to Use

- Building new UI layouts or pages
- Styling existing components
- Integrating shadcn-svelte (bits-ui) primitives
- Working with the ECharts theme
- Implementing dark/light mode theming

# When NOT to Use

- Writing Svelte component logic without styling concerns (defer to `svelte`)
- Writing tests for components (defer to `flow-testing-svelte`)
- Database or backend changes (defer to `supabase-project`)
- Projects whose UI layer is a non-Tailwind design system: Material UI
  (`@mui/material`), Chakra (`@chakra-ui/react`), Bootstrap, Bulma,
  `styled-components`, `@emotion/*`, `@vanilla-extract/*`, or pure CSS
  Modules / CSS-in-JS with no Tailwind context.
- Portable, stack-agnostic design/UX judgment (visual hierarchy, spacing
  rhythm, accessibility, the critique gate) lives in `universal/flow-ui-ux`; this
  skill is the Tailwind/shadcn mechanics layer that renders that judgment.

# Context

- Base UI components (shadcn-svelte): `src/lib/components/ui/`
- Layout shell: `src/lib/components/layout/` (e.g., `AuthenticatedLayout.svelte`)
- Design tokens and CSS variables: `src/app.css` (`:root` and `.dark` blocks)
- Icons: `@lucide/svelte` (the maintained scoped package; import individually: `import { ChevronDown } from "@lucide/svelte"`). Older projects may still use `lucide-svelte` — both work but `@lucide/svelte` is the current package.
- Toasts: `svelte-sonner` (import `toast` from `"svelte-sonner"` — `<Toaster>` is already mounted in the root layout)
- Class utility: `cn()` from `$lib/utils` (wraps `clsx` + `tailwind-merge`)
- Tailwind v4 configuration: CSS-first via `@theme inline` in `src/app.css` (minimal `tailwind.config.js` for content globs and font family)
- Tailwind v4 details: `references/tailwind-v4.md`
- Design token reference: `references/design-tokens.md`
- Design craft principles: `references/design-craft.md`
- Component patterns (layout, forms, bits-ui child snippets): `references/component-patterns.md`
- Post-build critique protocol: `references/critique-protocol.md`

# Instructions

## 1. Clarify Design Intent

Before writing any code, answer these questions (mentally for minor changes, explicitly for new
components or pages):

- **Who** is the user and what must they accomplish here?
- **Feel** — what should this feel like? (e.g., data-dense dashboard, clean onboarding, focused
  detail view)
- **Reject** — what default are you consciously avoiding? Name at least one.
- **Reference** — does an existing page or component in the app set a precedent to follow?

For minor styling tweaks (color change, spacing fix), a quick mental check suffices. For new
components or significant redesigns, state the intent before proceeding.

For the portable anti-default philosophy see `universal/flow-ui-ux`; for this repo's domain context and how it maps to Tailwind tokens see `references/design-craft.md`.

## 2. Check Existing Components

**CRITICAL:** Always check `src/lib/components/ui/` for shadcn-svelte primitives before building
custom ones.

### Import styles

shadcn-svelte components use two import patterns depending on whether they have subparts:

**Compound (namespace) import** — for multi-part components:

```svelte
import * as Card from "$lib/components/ui/card";
<!-- then use <Card.Root>, <Card.Header>, <Card.Title>, <Card.Content>, <Card.Footer> -->
```

**Named import** — for single-element components:

```svelte
import {Button} from "$lib/components/ui/button";
```

### Component quick reference

| Import Style              | Components                                                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Compound** (`import *`) | `AlertDialog`, `Calendar`, `Card`, `Collapsible`, `Combobox`, `Dialog`, `DropdownMenu`, `Popover`, `Select`, `ToggleGroup`, `Tooltip` |
| **Named** (`import { }`)  | `Button`, `Input`, `Label`, `Separator`, `Skeleton`, `Toggle`, `InlineLabel`                                                          |
| **Special**               | `Toaster` from `$lib/components/ui/sonner` (already mounted in root layout)                                                           |

### bits-ui child snippet

When compound Trigger components need a custom element instead of the default `<button>`, use
the `child` snippet pattern. This is common when composing triggers with styled Buttons or nesting
multiple trigger components. See `references/component-patterns.md` for the full pattern and
nested composition examples.

### Usage example

```svelte
<script lang="ts">
  import { Button } from "$lib/components/ui/button";
  import * as Dialog from "$lib/components/ui/dialog";
</script>

<Dialog.Root>
  <Dialog.Trigger>
    <Button variant="outline">Open</Button>
  </Dialog.Trigger>
  <Dialog.Content>
    <Dialog.Header>
      <Dialog.Title>Confirm Action</Dialog.Title>
      <Dialog.Description>Are you sure?</Dialog.Description>
    </Dialog.Header>
    <Dialog.Footer>
      <Button variant="ghost">Cancel</Button>
      <Button>Confirm</Button>
    </Dialog.Footer>
  </Dialog.Content>

From gavingolden/flow, MIT.

More from gavingolden/flow