You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat(core/cli): polling file watcher fallback for Builder dev (BuilderIO#668)
* feat(core/cli): polling file watcher fallback for Builder dev environments
Detects Builder.io dev containers and enables chokidar polling (1s interval) to work around container inotify limits. Honors explicit AGENT_NATIVE_DEV_USE_POLLING / WORKSPACE_USE_POLLING_WATCHER / CHOKIDAR_USEPOLLING overrides.
* style(core/cli): drop nested spread when building per-app env
* fix(core/cli): strip CHOKIDAR_USEPOLLING when polling explicitly disabled
When shouldUsePollingFileWatcher returns false (e.g. AGENT_NATIVE_DEV_USE_POLLING=0), devWatcherEnv was returning the env unchanged — so a parent-shell CHOKIDAR_USEPOLLING=1 still leaked into children and they kept polling. Now we strip the chokidar/TSC watcher vars when polling is explicitly disabled so the user's override actually wins. Addresses two builder-io-integration bot review comments on PR BuilderIO#668.
* fix: address PR BuilderIO#667 review feedback
Three follow-up fixes from the builder-io-integration bot review on the merged PR BuilderIO#667:
- dispatch/app-creation-store: partial metadata updates were silently wiping unmodified fields. Treat `description == null` as 'omitted, preserve existing'; only explicit empty string clears it.
- core/workspace-deploy: filter loopback origins out of the workspaceOAuthOrigin gateway-URL fallback so a misconfigured prod deploy can't silently redirect users to localhost. Explicit env-var overrides still pass through loopback intentionally.
- slides/tab-id: detect duplicated browser tabs (which inherit sessionStorage and would otherwise share a tab id) with a BroadcastChannel handshake; the duplicate tab regenerates and re-announces. Skipped the bot's separate 'drop global navigate fallback' suggestion — the fallback is intentional for CLI compat where no browserTabId header is sent.
* feat(core/server): app-url + google-oauth refinements, loopback filtering followups
* test(core/server): expand auth.spec coverage
* style(core): prettier format auth.spec
* test(core/deploy): workspace-deploy spec coverage + workspace-oauth-public-origins changeset
* docs(agents): add shadcn-ui skill + frontend-design refinements
* docs(agents): propagate shadcn-ui skill + frontend-design refinements to all templates
* chore: add changeset for shadcn-workspace-skills
* docs(agents): reference shadcn-ui skill from AGENTS.md across workspace tiers
* style(core): prettier format AgentPanel
* chore: add changeset for builder-web-agent-panel
* test(core/cli): expand create-e2e spec coverage for shadcn skill propagation
This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
15
+
This skill guides creation of distinctive, production-grade frontend interfaces. Implement real working code with strong product judgment, excellent accessibility, and a clear visual point of view.
16
16
17
-
The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
17
+
The user may ask for a component, page, full app, dashboard, marketing surface, or restyle. Before coding, understand the audience and pick a direction that fits the product instead of defaulting to generic SaaS polish.
18
18
19
19
## Design Thinking
20
20
21
-
Before coding, understand the context and commit to a BOLD aesthetic direction:
22
-
-**Purpose**: What problem does this interface solve? Who uses it?
23
-
-**Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
-**Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
21
+
Before coding, decide:
26
22
27
-
**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.
23
+
-**Purpose**: What workflow does this surface make easier? What is the primary action?
24
+
-**Audience**: Who will use it repeatedly, and what should feel fast, calm, playful, premium, editorial, technical, or utilitarian?
25
+
-**Tone**: Choose a concrete aesthetic direction: refined minimal, dense operations console, editorial, playful, industrial, warm handmade, high-contrast data tool, etc.
26
+
-**Information hierarchy**: What must be visible in the first five seconds, and what should be progressively disclosed?
27
+
-**Differentiation**: What makes this feel designed for this exact domain?
28
28
29
-
Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
30
-
- Production-grade and functional
31
-
- Visually striking and memorable
32
-
- Cohesive with a clear aesthetic point-of-view
33
-
- Meticulously refined in every detail
29
+
Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, copy, motion, empty states, loading states, focus states, and error states.
34
30
35
-
## Frontend Aesthetics Guidelines
31
+
## Aesthetic Guidelines
36
32
37
-
Focus on:
38
-
-**Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
39
-
-**Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
40
-
-**Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (`animation-delay`) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
41
-
-**Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
42
-
-**Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
33
+
-**Typography**: Use the product's existing type system first. For net-new public pages, choose characterful but readable type and keep sizing appropriate to the surface.
34
+
-**Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes and default purple/blue gradients unless the brand demands them.
35
+
-**Motion**: Prefer purposeful transitions and small state changes. Use CSS transitions/keyframes unless the app already uses a motion library.
36
+
-**Composition**: Match the workflow. Operational apps should be dense and scannable; marketing or portfolio pages can be more immersive.
37
+
-**Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
38
+
-**Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
43
39
44
-
## Anti-Patterns to Avoid
40
+
## Agent-Native UI Rules
45
41
46
-
NEVER use generic AI-generated aesthetics like:
47
-
- Overused font families (Inter, Roboto, Arial, system fonts)
48
-
- Clichéd color schemes (particularly purple gradients on white backgrounds)
49
-
- Predictable layouts and component patterns
50
-
- Cookie-cutter design that lacks context-specific character
42
+
- Agent-native apps use React, Vite, Tailwind CSS, shadcn/ui, and `@tabler/icons-react`.
43
+
-**Use shadcn/ui primitives for standard UI**: `DropdownMenu`, `Popover`, `Dialog`, `AlertDialog`, `Sheet`, `Tabs`, `Tooltip`, `Select`, `Command`, `Sidebar`, `Table`, `Card`, `Badge`, `Skeleton`, and related primitives.
44
+
-**When touching shadcn/ui components, also read `shadcn-ui` if it exists.** That skill covers `components.json`, CLI docs, component composition, theming, and registry workflows.
45
+
- Check `app/components/ui/` before importing a shadcn component. If a primitive is missing, add it from the app root with `pnpm dlx shadcn@latest add <component>`, then review the generated file.
46
+
- Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
47
+
- Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
48
+
- Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
49
+
- Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
50
+
- Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
51
+
- Custom styles belong in Tailwind classes, component CSS, or the existing global CSS theme file; avoid inline styles.
51
52
52
-
Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
53
+
## shadcn/ui Design Rules
53
54
54
-
## Implementation Notes
55
+
- Use built-in component variants first (`variant`, `size`) before overriding classes.
56
+
- Use semantic tokens (`bg-background`, `text-muted-foreground`, `border-border`, `bg-primary`) instead of raw Tailwind colors for app chrome and reusable components.
57
+
- Use `gap-*` in flex/grid layouts instead of `space-x-*` or `space-y-*`.
58
+
- Use `size-*` when width and height are equal, and `truncate` instead of spelling out overflow/ellipsis/nowrap.
59
+
- Use `cn()` from the local utils alias for conditional classes.
60
+
- Dialog, Sheet, Drawer, and AlertDialog content must have an accessible title. Use `sr-only` only when the visible design already communicates the title.
61
+
- Put menu/list items inside their group primitives: `SelectGroup`, `DropdownMenuGroup`, `CommandGroup`, and equivalents.
62
+
- Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
63
+
- Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
64
+
- For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
65
+
- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
55
66
56
-
**Match implementation complexity to the aesthetic vision.** Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
67
+
## Anti-Patterns
57
68
58
-
In the agent-native framework context:
59
-
- Agent-native apps use React 18, Vite, TailwindCSS, and shadcn/ui
60
-
-**Always use shadcn primitives for menus, popovers, dialogs, tooltips, sheets, and tabs.** Check `app/components/ui/` first; if the primitive is missing, run `npx shadcn@latest add <name>`. Never roll your own with `position: absolute` + a click-outside `useEffect` — it gets clipped by ancestor stacking contexts and lacks keyboard / focus / animation behavior. Specifically: `<DropdownMenu>` for action menus (Rename / Delete / "⋯"), `<Popover>` for transient panels, `<Dialog>` for modals, `<AlertDialog>` for confirms (never `window.confirm`), `<Sheet>` for side drawers, `<HoverCard>` for hover detail.
61
-
- Custom styles go in component CSS or Tailwind classes — never inline styles
62
-
- For complex visual effects, use a `<style>` tag in the component or a dedicated CSS file
63
-
- Fonts can be loaded from Google Fonts via `@import` in a CSS file or `<link>` in `index.html`
64
-
- Animation libraries: prefer CSS transitions and keyframes; use Framer Motion for complex sequences
65
-
- All new UI components should be placed in `app/components/`
66
-
-**Data fetching**: Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` to call actions. Actions are auto-exposed as HTTP endpoints — no need to create separate `/api/` routes for standard CRUD.
69
+
Avoid:
70
+
71
+
- Generic AI aesthetics: purple gradients, glassy cards everywhere, vague sparkle language, decorative blobs, and context-free hero sections.
72
+
- Custom reimplementations of shadcn primitives.
73
+
- Raw color overrides on shared components when semantic tokens or variants would work.
74
+
- New always-visible controls for rare actions. Prefer menus, popovers, sheets, tabs, collapsibles, or advanced sections.
75
+
- UI cards nested inside other cards.
76
+
- Text or icons that resize or shift fixed-format UI on hover/loading.
77
+
78
+
## Verification
79
+
80
+
For substantial frontend work:
81
+
82
+
1. Run the relevant formatter/checks.
83
+
2. Start the dev server when the app needs one.
84
+
3. Verify with browser screenshots at desktop and mobile widths.
Use when adding, updating, debugging, styling, or composing shadcn/ui
5
+
components, forms, dialogs, menus, charts, sidebars, themes, registries, or
6
+
any project with a components.json file.
7
+
source: https://ui.shadcn.com/docs/skills
8
+
---
9
+
10
+
# shadcn/ui
11
+
12
+
This skill keeps shadcn/ui work project-aware. Components are source files in the app, so always inspect the local project before adding, importing, or rewriting them.
13
+
14
+
## First Steps
15
+
16
+
1. Work from the app root that owns `components.json`.
17
+
2. Run `pnpm dlx shadcn@latest info --json` when you need current project context: framework, Tailwind version, aliases, icon library, installed components, and resolved paths.
18
+
3. Use the actual aliases from `components.json` or `shadcn info`; do not assume `@/components/ui` if the project says otherwise.
19
+
4. Check `app/components/ui/` or the resolved `ui` path before importing a component.
20
+
5. For unfamiliar components, run `pnpm dlx shadcn@latest docs <component>` and read the returned docs or examples before coding.
21
+
22
+
## Adding Or Updating Components
23
+
24
+
- Add missing primitives with `pnpm dlx shadcn@latest add <component>` from the app root.
25
+
- Before overwriting an existing component, use `pnpm dlx shadcn@latest add <component> --dry-run` and `--diff` to inspect the change.
26
+
- After adding registry code, read the generated files. Fix import aliases, icon imports, missing subcomponents, and composition issues before using the component.
27
+
- Do not fetch raw component files manually from GitHub when the shadcn CLI can resolve the registry item.
28
+
- If a user asks to add a third-party block but does not name a registry, ask which registry to use instead of guessing.
29
+
30
+
## Component Composition
31
+
32
+
- Use existing primitives before custom markup: `Alert` for callouts, `Badge` for small status labels, `Separator` for dividers, `Skeleton` for placeholders, `Table` for tabular data, and `Card` for framed content.
33
+
- Use full card anatomy when appropriate: `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, and `CardFooter`.
34
+
- Dialog, Sheet, Drawer, and AlertDialog content must include an accessible title. Use visually hidden titles only when the visible UI already communicates the title.
35
+
- Put items inside their group components: `SelectItem` in `SelectGroup`, `DropdownMenuItem` in `DropdownMenuGroup`, `CommandItem` in `CommandGroup`, and equivalent menu groups.
36
+
-`TabsTrigger` belongs inside `TabsList`.
37
+
-`Avatar` always needs `AvatarFallback`.
38
+
- Buttons do not have magic loading props. Compose loading with `disabled`, `Spinner`, and clear text.
39
+
40
+
## Forms And Inputs
41
+
42
+
- Use the app's shadcn form primitives instead of raw div stacks.
43
+
- If `Field`, `FieldGroup`, `FieldSet`, or `InputGroup` are installed or worth adding, use them for form layout, grouped fields, and input add-ons.
44
+
- Do not place buttons inside inputs with absolute positioning. Use `InputGroup` and `InputGroupAddon` when available.
45
+
- Use `ToggleGroup` for small option sets, `RadioGroup` for one-of-many choices, `Checkbox` for multi-select, `Switch` for settings toggles, `Select` or `Combobox` for predefined choices, and `Slider` or numeric input for numeric values.
46
+
- Validation must be accessible: pair visual invalid states with `aria-invalid`, and connect descriptions/errors to controls.
47
+
48
+
## Styling And Theming
49
+
50
+
- Use semantic tokens (`bg-background`, `text-foreground`, `text-muted-foreground`, `bg-primary`, `border-border`, `text-destructive`) instead of raw colors for reusable app UI.
51
+
- Prefer built-in variants and sizes before custom classes.
52
+
- Use `className` mostly for layout and spacing; avoid overriding component colors and typography unless the component is intentionally being extended.
53
+
- Use `gap-*` instead of `space-x-*` / `space-y-*`.
54
+
- Use `size-*` when width and height are equal.
55
+
- Use `truncate` for single-line clipping.
56
+
- Use `cn()` for conditional classes.
57
+
- Do not add manual `z-index` to overlay primitives unless you are fixing a verified stacking bug.
58
+
- Add custom colors as CSS variables in the existing Tailwind CSS file reported by shadcn info. For Tailwind v4, register variables with `@theme inline`.
59
+
60
+
## Icons
61
+
62
+
- Agent-native apps use `@tabler/icons-react`. Do not add `lucide-react` because a registry example used it.
63
+
- If registry code imports a different icon package, replace those imports with Tabler equivalents before finishing.
64
+
- Let shadcn components size icons through their CSS. Avoid manual icon sizing inside buttons, menus, alerts, and sidebars unless the local component API requires it.
65
+
66
+
## Base-Specific APIs
67
+
68
+
Check the project context before using trigger composition APIs:
69
+
70
+
- Radix-based components use `asChild` for custom triggers.
71
+
- Base UI components may use `render` and sometimes `nativeButton={false}`.
72
+
73
+
Do not wrap triggers in extra divs just to place a Button or Link inside them.
74
+
75
+
## Related Skills
76
+
77
+
-**frontend-design** — Product UX, visual direction, responsive polish, and verification
78
+
-**actions** — Data fetching and mutation patterns for agent-native apps
79
+
-**security** — User data, forms, external input, and action safety
0 commit comments