styling-with-tailwind-shadcn
Skill11 starsChanged 51 days agoMITView on GitHub
Implements the Calm Tech design system using Tailwind CSS v4 and Shadcn UI. Use when writing styles, building components, or theming. For design decisions, see designing-frontend.
In this repository44 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- auditing-uiSkill
- browser-testingSkill
- capturing-product-mediaSkill
- ci-local-exportSkill
- ci-pulseSkill
- ci-quarantineSkill
- ci-statusSkill
- creating-pull-requestsSkill
- debugging-systematicallySkill
- debugging-test-failuresSkill
- debugging-typescript-errorsSkill
- deps-weeklySkill
- designing-frontendSkill
- opensrcSkill
- organizing-fsd-architectureSkill
- runtime-watchSkill
- stewarding-ci-pipelineSkill
- syncing-agent-skillsSkill
- verification-before-completionSkill
- vision-drift-checkSkill
- visual-companionSkill
- writing-adrsSkill
- writing-app-copySkill
- writing-blog-postsSkill
- writing-changelogsSkill
- writing-developer-guidesSkill
- writing-for-humansSkill
- writing-to-usersSkill
- adding-config-fieldsSkill
- clarifying-requirementsSkill
- maintaining-dependenciesSkill
- maintaining-dev-playgroundSkill
- managing-specsSkill
- marketplace-devSkill
- orchestrating-parallel-workSkill
- reading-session-transcriptsSkill
- receiving-code-reviewSkill
- requesting-code-reviewSkill
- test-driven-developmentSkill
- upgrading-runtime-dependenciesSkill
- working-in-worktreesSkill
- dorkbot-triageSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 3 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
For design thinking (what/why): Use the designing-frontend skill.
- Very specific: line 12
All tokens and utilities live in apps/client/src/index.css (there is no tailwind.config.js and no globals.css — this is a Vite SPA, not …
- Very specific: line 76
After installing, adapt the component to project conventions: imports resolve to @/layers/shared/ui and @/layers/shared/lib/utils via the …
- Very specific: line 97
Do not use a render prop — that is a Base UI pattern and its primitives are not in this project (package.json has @radix-ui/* deps only).
- Distinctive: line 127
Never use pure black or white: Use the semantic tokens.
- Very specific: line 289
Only a genuinely-happening-now state animates.
- Very specific: line 293
Use the Motion library (motion/react) for animations (see contributing/animations.md):
- Very specific: line 327
Always use cn() for conditional classes:
- Very specific: line 355
Use Tailwind's first-party scrollbar-* utilities (v4.3+).
- Very specific: line 366
Follow the shipped components: check shared/ui/ source for the real variant/size API before styling around it
- Distinctive: line 367
Respect the type scale: use the token sizes; let the mobile dial do responsive scaling
- Distinctive: line 371
Test dark mode: ensure proper contrast in both themes
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Styling with Tailwind CSS v4 & Shadcn UI
This skill provides implementation patterns for the Calm Tech design system using Tailwind CSS v4 (CSS-first configuration) and shadcn/ui (new-york style) on Radix primitives.
For design thinking (what/why): Use the designing-frontend skill.
All tokens and utilities live in apps/client/src/index.css (there is no tailwind.config.js and no globals.css — this is a Vite SPA, not Next.js).
Current Documentation (Context7)
Tailwind v4 uses CSS-first configuration. For current patterns:
# Check installed version
grep '"tailwindcss"' apps/client/package.json
# Fetch Tailwind v4 docs
mcp__context7__resolve-library-id: { libraryName: "tailwindcss" }
mcp__context7__query-docs: {
context7CompatibleLibraryID: "[resolved-id]",
topic: "[specific topic, e.g., '@theme directive', 'dark mode', 'custom utilities']"
}
# Fetch Shadcn docs
mcp__context7__resolve-library-id: { libraryName: "shadcn" }
mcp__context7__query-docs: {
context7CompatibleLibraryID: "[resolved-id]",
topic: "[component name, e.g., 'Button', 'Form', 'Dialog']"
}When to fetch docs:
- Uncertain about Tailwind v4 CSS-first syntax
- Adding new shadcn components
- Implementing theming or dark mode
- Understanding Radix primitive behavior
When to Use
- Writing Tailwind classes for components
- Implementing dark mode theming
- Using the
cn()utility for conditional classes - Customizing Shadcn UI components
- Adding animations with Motion library
Installing Components
This project uses shadcn/ui (new-york style, Radix primitives). Config lives in apps/client/components.json; installed components land in apps/client/src/layers/shared/ui/:
# From apps/client/ — install from the default shadcn registry
npx shadcn@latest add <component>
# Examples
npx shadcn@latest add button
npx shadcn@latest add dialog
npx shadcn@latest add selectOne extra registry is configured (@aceternity for effect components):
{
"registries": {
"@aceternity": "https://ui.aceternity.com/registry/{name}.json"
}
}After installing, adapt the component to project conventions: imports resolve to @/layers/shared/ui and @/layers/shared/lib/utils via the aliases in components.json, and new components should use ref-as-prop (React 19), not forwardRef.
Composition: asChild
Radix composition uses the asChild prop (backed by Slot from radix-ui). This is the established pattern (~144 uses in apps/client/src) — use it for all new code:
// Render a Button as a link
<Button asChild>
<a href="/contact">Contact</a>
</Button>
// SidebarMenuButton wrapping a router link
<SidebarMenuButton asChild>
<Link to={item.href}>
<Icon className="size-4" />
<span>{item.label}</span>
</Link>
</SidebarMenuButton>Do not use a render prop — that is a Base UI pattern and its primitives are not in this project (package.json has @radix-ui/* deps only). See .claude/rules/components.md for full component rules.
Typography
System font stacks — no webfonts are shipped:
/* apps/client/src/index.css */
--font-sans: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
--font-mono: ui-monospace, 'SF Mono', 'Cascadia Code', 'Fira Code', Menlo, Consolas, monospace;Type scale: standard Tailwind rem sizes, redefined in @theme inline so every size is multiplied by the mobile scale (--_st, 1.25x below 768px) and the user's font-scale preference (--user-font-scale). Two extra sub-xs sizes exist for dense UI chrome:
| Class | Base size | Usage |
text-3xs | 0.625rem (10px) | Tiny metadata, dense chrome |
text-2xs | 0.6875rem (11px) | Badges, timestamps |
text-xs | 0.75rem (12px) | Labels, captions |
text-sm | 0.875rem (14px) | Secondary text, most UI text |
text-base | 1rem (16px) | Body text |
text-lg | 1.125rem (18px) | Emphasized body, card titles |
text-xl | 1.25rem (20px) | Section headings |
Sizes above xl (text-2xl+) fall through to Tailwind defaults and are not mobile-scaled. Because the scale multiplies at the token level, do not hand-roll responsive font sizes for standard UI text — the dial in index.css handles it.
Color System
Colors are HSL CSS variables defined per theme (:root / .dark) and bridged to Tailwind utilities via @theme inline (--color-primary: hsl(var(--primary)) etc.).
Never use pure black or white. Use the semantic tokens.
Semantic Colors
// Primary actions
<Button className="bg-primary text-primary-foreground" />
// Secondary actions
<Button variant="secondary" className="bg-secondary text-secondary-foreground" />
// Destructive actions
<Button variant="destructive" />
// Muted/secondary text
<p className="text-muted-foreground">Secondary information</p>Status Colors
Status tokens use the status-* namespace with -bg / -border / -fg companions (success, error, warning, info, pending):
// Icon or text in the status color
<Check className="text-status-success" />
// Tinted chip: background + matching foreground
<span className="bg-status-success-bg text-status-success-fg">Approved</span>
<span className="bg-status-error-bg text-status-error-fg border-status-error-border border">Failed</span>Dark Mode
Dark mode is class-based: @custom-variant dark (&:is(.dark *)) in index.css, with the .dark class toggled on <html> by the local useTheme hook (@/layers/shared/model) — light / dark / system, persisted to localStorage. There is no next-themes.
import { useTheme } from '@/layers/shared/model';
const { theme, setTheme } = useTheme();
setTheme(theme === 'dark' ? 'light' : 'dark'); // or 'system'
// Components adapt automatically via semantic tokens
<div className="bg-background text-foreground" />;Sizing Tokens (Mobile-Scaled)
Icon and interactive-element sizes are tokens in @theme inline, multiplied by the mobile dial like text:
// Icons: --size-icon-xs / -sm / -md
<Check className="size-(--size-icon-sm)" />
// Interactive heights: --size-btn-sm / -md / -lg
<div className="h-(--size-btn-md)" />Component Specifications
Buttons (shared/ui/button.tsx)
Desktop heights; the responsive behavior bumps sizes on mobile (e.g. h-11 md:h-9):
| Size | Height | Usage |
xs | 24px (h-6) | Dense UI chrome |
sm | 32px (h-8) | Compact actions |
default | 36px (h-9) | Standard actions |
lg | 40px (h-10) | Primary CTAs |
icon | 36px (size-9) | Icon-only buttons |
Icon-only variants: icon-xs, icon-sm, icon-lg.
Inputs (shared/ui/input.tsx)
- Height: 36px (
h-9), orh-11 md:h-9whenresponsive - Border radius:
rounded-md - Shadow:
shadow-xs
Radius
Buttons and inputs use rounded-md; cards and modals use rounded-xl. The project uses Tailwind's default radius scale (no custom --radius-* overrides beyond message-specific tokens like --radius-msg).
Control Surfaces
Sidebars, toolbars, list panes, menus and table rows are control surfaces — operated many times an hour, so they run dense. Pages, cards and empty states keep the generous spacing. designing-frontend → Two Spatial Modes decides which one you are building.
The dense row
<div className="group/row hover:bg-muted/50 flex h-7 items-center gap-2 rounded-md px-2 text-[13px]">
<Icon className="text-muted-foreground size-(--size-icon-xs) shrink-0" />
<span className="truncate">{label}</span>
<span className="text-2xs text-muted-foreground ml-auto">{meta}</span>
</div>- Height —
h-7(28px), orh-8(32px) when the row carries an avatar. 4px-grid multiples only. - Text — 13px label,
text-2xs(11px) metadata. - Inset — 16px total, paid once. Panel edge to first glyph. If the scroll container pays
px-2, the row payspx-2and nothing in between pays anything. Stacking container + section + row padding is how a sidebar ends up with a 30px gutter. - Nav panel width — 240–280px.
text-[13px] is an arbitrary value, so it does not ride the --_st mobile dial — there is no token between text-xs (12px) and text-sm (14px). On a surface that also renders on mobile, write text-sm md:text-[13px]: mobile keeps the scaled token, desktop gets the dense size.
Hover-reveal
Row and section actions render nothing at rest:
<Button
size="icon-xs"
variant="ghost"
aria-label="Row actions"
className={cn(
'transition-opacity focus-visible:opacity-100',
// hidden only where a pointer can hover; always there on touch
'[@media(hover:hover)]:opacity-0 [@media(hover:hover)]:group-hover/row:opacity-100'
)}
>
<MoreVertical className="size-(--size-icon-xs)" />
</Button>Three non-negotiables:
- Name the group. Bare
group-hover:compiles to:where(.group):hover &and matches any.groupancestor — the sidebar's outer group left every nested affordance permanently visible. Usegroup/row+group-hover/row:. focus-visible:parity. A keyboard user must never learn less than a mouse user.- A touch path. Gate the hiding on
[@media(hover:hover)](the query asks about the pointer, not the viewport) so touch gets the action outright, or route it to long-press / context menu. Anything draggable needs a non-drag alternative — WCAG 2.2 §2.5.7.
Overflow glyph: vertical kebab (MoreVertical, ⋮) for row and section overflow; MoreHorizontal (⋯) is toolbar and table vocabulary. Vertical also needs less reserved gutter — keep that gutter as narrow as the icon.
Separation: tint, not lines
// A zone, separated by tint rather than a rule
<section className="bg-muted/40 rounded-lg" />
// Hover is the same mechanism, one step
<div className="hover:bg-muted/50" />Order of preference: gap → 5–10% background tint → elevation (shadow-soft, shadow-elevated, scarce). No border-b under a panel header, no border-t above a footer.
Scroll-edge shadow
The header detaches only once content is under it:
const [scrolled, setScrolled] = useState(false);
<header className={cn('transition-shadow', scrolled && 'shadow-soft')}>{title}</header>
<div className="overflow-y-auto" onScroll={(e) => setScrolled(e.currentTarget.scrollTop > 0)}>
{rows}
</div>For a virtualized or very long list, put a 1px sentinel at the top of the scroll content and drive the same boolean from an IntersectionObserver — cheaper than a scroll handler firing every frame.
Status colors on control surfaces
Agent and job state comes from the status-* tokens (success, error, warning, info, pending — see Status Colors). Never text-green-500 for healthy, never bg-primary for a state: primary is a button color, and a status painted with it stops meaning anything the moment a button sits next to it.
Only a genuinely-happening-now state animates. bg-status-success with a pulse means working right now; idle, done and error are static fills.
Animations with Motion
Use the Motion library (motion/react) for animations (see contributing/animations.md):
import { motion, AnimatePresence } from 'motion/react';
// Duration scale
const duration = {
fast: 0.1, // 100ms - micro-interactions
normal: 0.15, // 150ms - standard transitions
slow: 0.2, // 200ms - layout shifts
slower: 0.3, // 300ms - modal enter/exit
};
// Fade in up (common pattern)
<motion.div
initial={{ opacity: 0, y: 20 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: 0.15, ease: [0, 0, 0.2, 1] }}
>
Content
</motion.div>
// Exit animations (require AnimatePresence)
<AnimatePresence>
{isOpen && (
<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }}>
Modal content
</motion.div>
)}
</AnimatePresence>cn() Utility
Always use cn() for conditional classes:
import { cn } from '@/layers/shared/lib/utils'
<button
className={cn(
'px-4 py-2 rounded-md',
isActive && 'bg-primary text-primary-foreground',
isDisabled && 'opacity-50 cursor-not-allowed'
)}
>
Button
</button>Responsive Design
Mobile-first with standard breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px), 2xl (1536px).
<div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">{/* Responsive grid */}</div>Text and icon sizes below 768px scale automatically via the token dial — prefer the tokens over per-component md: font overrides.
Scrollbars
Use Tailwind's first-party scrollbar-* utilities (v4.3+); never hand-roll scrollbar-width or ::-webkit-scrollbar CSS:
scrollbar-none— hide the native scrollbar, keep scroll (status strip, containers with custom scroll overlays)scrollbar-thin— thin visible scrollbar (theindex.cssbase style already thins everything; rarely needed per-component)scrollbar-gutter-stable— reserve gutter space so conditionally-scrolling dialog/panel bodies don't shift layout on classic-scrollbar platforms
For a styled, fading thumb, use the Radix ScrollArea primitive from shared/ui instead.
Best Practices
- Use semantic color names:
bg-primarynotbg-blue-500;text-status-errornottext-red-500 - Follow the shipped components: check
shared/ui/source for the real variant/size API before styling around it - Respect the type scale: use the token sizes; let the mobile dial do responsive scaling
- Pick the spatial mode first: dense recipes for control surfaces, generous spacing for content
- Separate with tint before a border:
bg-muted/40overborder-b - Apply animations thoughtfully: one well-orchestrated animation beats many scattered ones
- Test dark mode: ensure proper contrast in both themes
Common Pitfalls
- Using
tailwind.config.js(use@themeinapps/client/src/index.cssinstead) - Hardcoding colors instead of semantic variables
- Using pure black (
#000) or white (#fff) - use theme colors - Inventing utilities that don't exist (verify custom classes against
index.cssbefore using them) - Stacking padding on a control surface (container + section + row) instead of budgeting the inset once
- Bare
group-hover:on a nested control — it matches any.groupancestor; name the group - Hiding an action on hover with no
focus-visible:twin and no touch path - Missing dark mode variants
- Over-animating - focus on high-impact moments
References
designing-frontendskill — Design thinking, hierarchy, component decisions.claude/rules/components.md— Component rules (composition, accessibility, tables)contributing/design-system.md— Full design language documentationcontributing/styling-theming.md— Practical styling patternscontributing/animations.md— Animation patternsapps/client/src/index.css— Implemented tokens and utilities
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
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.

