@oneie/claude 0.6.0 → 0.8.0

package/skills/shadcn/SKILL.md

@@ -1,13 +1,22 @@
 ---
 name: shadcn
-description: Use shadcn/ui components for the Envelope System UI - Cards, Tabs, Badges, and dark theme patterns
+description: shadcn/ui primitives in `one.ie/web` under the ONE 6-token design system. Covers the `src/components/ui/` inventory, why shadcn's own `-foreground` names survive the `--color-*: initial` palette wipe via the Layout.astro aliases, adding a primitive with the CLI, and Button/Badge/Card/Dialog variants. Use when adding or editing a `src/components/ui/` primitive, when a shadcn component renders transparent or invisible after the wipe, or when picking between a token utility and an alias.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 ---
 
 # shadcn/ui Development
 
-Build consistent UI with shadcn/ui components, customized for the Envelope System's dark theme.
+Build UI in `one.ie/web` with shadcn primitives on the ONE 6-token design system.
+
+This skill covers the seam that the auto-loaded rules do not: **how shadcn's own
+naming convention (`bg-card`, `text-muted-foreground`, `text-primary-foreground`)
+survives the `--color-*: initial` palette wipe.** For the token list, the allowed
+utilities, and the ban list, read `.claude/rules/design.md` — it auto-loads on the
+same files and is already in context when you edit.
+
+Scope: `one.ie/web`. For `template/site` use the `template:shadcn` skill; for
+generic registry/CLI operations outside this repo use the `shadcn` plugin skill.
 
 ## Works With
 
@@ -15,56 +24,102 @@ Build consistent UI with shadcn/ui components, customized for the Envelope Syste
 |------------|------------------------------------------------------------------------------|
 | `/react19` | shadcn components ARE React components — ref-as-prop, Actions, transitions apply. |
 | `/astro`   | Placement inside islands + hydration strategy decisions.                       |
-| `/signal`  | Buttons, menus, dialogs — every semantic click emits `ui:<surface>:<action>`. |
+| `/puck`    | Every Puck block wraps a real component — brand tokens reach the editor iframe. |
 | `/ai-ui`   | AI Elements (reasoning cards, tool-call blocks) compose shadcn primitives.    |
 
-Auto-loads on `*.tsx`: `rules/react.md` + `rules/ui.md` (per `.claude/settings.json`).
+Auto-loads on these files, via each rule's own `paths:` frontmatter (not
+`settings.json`, which wires hooks only):
+
+| Rule | Glob |
+|---|---|
+| `rules/react.md` | `**/*.tsx` |
+| `rules/ui.md` | `one.ie/web/src/components/**/*.tsx` |
+| `rules/design.md` | `one.ie/web/**/*.{tsx,astro,css}` |
 
 ## When to Use This Skill
 
-- Use existing shadcn components from `src/components/ui/`
-- Customize component variants
-- Add new shadcn components
-- Apply the dark theme color system
-- Build composite components
+- Use existing primitives from `one.ie/web/src/components/ui/`
+- Add a new primitive with the shadcn CLI
+- Customize a variant (`cva` blocks in `button.tsx`, `badge.tsx`)
+- Fix a primitive that renders transparent or invisible after the palette wipe
+- Build composite components on top of the primitives
 
 ## Available Components
 
-The project includes these shadcn/ui components in `src/components/ui/`:
-
-| Component | Import | Use Case |
-|-----------|--------|----------|
-| `Card` | `@/components/ui/card` | Envelopes, agents, panels |
-| `Tabs` | `@/components/ui/tabs` | Agent tabs in top panel |
-| `Badge` | `@/components/ui/badge` | Status indicators |
-| `Button` | `@/components/ui/button` | Actions, submissions |
-| `ScrollArea` | `@/components/ui/scroll-area` | Scrollable lists |
-| `Separator` | `@/components/ui/separator` | Visual dividers |
-| `Tooltip` | `@/components/ui/tooltip` | Hover information |
-| `Dialog` | `@/components/ui/dialog` | Modals |
-| `Accordion` | `@/components/ui/accordion` | Collapsible sections |
-
-## Color System (Dark Theme)
-
-```css
-/* Primary colors */
---background: #0a0a0f;        /* Near-black */
---foreground: #ffffff;        /* White text */
-
-/* Status colors */
---status-ready: #22c55e;      /* Green - ready/resolved */
---status-pending: #eab308;    /* Amber - pending/waiting */
---status-idle: #64748b;       /* Slate - idle */
---status-error: #ef4444;      /* Red - error/rejected */
-
-/* Borders and accents */
---border: #1e293b;            /* Subtle borders */
---accent: #3b82f6;            /* Blue accent */
+`one.ie/web/src/components/ui/` holds **57 files**. They are not all shadcn:
+
+**shadcn primitives** — generated by the CLI, backed by the unified `radix-ui`
+package (`^1.4.3`, imported as `import { Dialog as DialogPrimitive } from "radix-ui"`
+— **not** the old `@radix-ui/react-*` scoped packages):
+
+`accordion` · `alert` · `aspect-ratio` · `avatar` · `badge` · `breadcrumb` ·
+`button` · `button-group` · `card` · `carousel` · `chart` · `checkbox` ·
+`collapsible` · `command` · `dialog` · `dropdown-menu` · `hover-card` ·
+`input` · `input-group` · `kbd` · `label` · `navigation-menu` · `pagination` ·
+`popover` · `progress` · `radio-group` · `scroll-area` · `select` · `separator` ·
+`sheet` · `skeleton` · `slider` · `spinner` · `switch` · `table` · `tabs` ·
+`textarea` · `toggle` · `toggle-group` · `tooltip`
+
+**ONE-local, not shadcn** — do not `shadcn add` over these, and do not assume
+upstream props: `Icon.tsx` · `IconBadge.tsx` · `EmptyCard.tsx` · `ImagePicker.tsx` ·
+`Drawer.tsx` · `global-toaster.tsx` · `multi-select.tsx` · `rating.tsx` ·
+`animated-tooltip.tsx` · `bounce-button.tsx` · `magnetic-button.tsx` ·
+`shimmer-button.tsx` · `motion-checkbox.tsx` · `motion-highlight.tsx` ·
+`motion-radio-group.tsx` · `motion-switch.tsx` · `motion-tabs.tsx`
+
+`components.json` pins `style: "radix-nova"`, `iconLibrary: "lucide"`,
+`cssVariables: true`, and `css: src/styles/globals.css`.
+
+## Color System — how shadcn names survive the wipe
+
+`Layout.astro` declares `--color-*: initial` inside `@theme`, which erases
+Tailwind's entire default palette. That is the enforcement layer: `bg-zinc-950`
+emits no CSS at all. It also erases every var a stock shadcn primitive expects.
+
+So `Layout.astro` re-declares the ones shadcn needs, aliased onto the 6 tokens.
+This is the mechanism to know — it is why you can write `bg-card` and
+`text-muted-foreground` in a primitive without adding a 7th token:
+
+```
+--color-popover:            var(--color-foreground)
+--color-popover-foreground: var(--color-font)
+--color-card:               var(--color-foreground)
+--color-card-foreground:    var(--color-font)
+--color-muted:              var(--color-foreground)
+--color-muted-foreground:   color-mix(font 60%, transparent)
+--color-accent:             var(--color-foreground)
+--color-accent-foreground:  var(--color-font)
+--color-input:              var(--color-background)
+--color-primary-foreground:   var(--color-on-primary)
+--color-secondary-foreground: var(--color-on-secondary)
 ```
 
+Two failure modes this prevents, both of which look like a bug in the component:
+
+1. **Transparent popovers.** Without `--color-card` / `--color-popover`, the
+   wiped var makes the `background-color` declaration invalid, so the panel
+   inherits nothing and floats see-through over the page.
+2. **Invisible glyphs on a brand fill.** Stock Button/Badge/Checkbox read
+   `text-primary-foreground`. Wiped, the color declaration is dropped and the
+   icon inherits an ancestor's `text-muted-foreground` — near-invisible on a
+   solid `bg-primary`. The alias points it at the already-WCAG-correct
+   `on-primary` label.
+
+**The one collision you must resolve by hand:** shadcn uses `foreground` to mean
+"body text on a card". ONE uses `foreground` as the L2 *surface* token (cards,
+sidebar, panels). They are not the same thing and there is no alias that can make
+them so. Any primitive that ships `text-foreground` for body text **must be edited
+to `text-font`** — otherwise the text paints the same color as its own background.
+`src/components/ui/` currently has zero `text-foreground` occurrences; keep it
+that way after every `shadcn add`.
+
+Fine as-is, no edit needed: `text-card-foreground`, `text-popover-foreground`,
+`text-muted-foreground`, `text-accent-foreground`, and the
+`text-{primary,secondary,destructive,sidebar}-foreground` contrast labels.
+
 ## Core Components
 
-### Card (Envelopes, Agents)
+### Card
 
 ```tsx
 import {
@@ -75,32 +130,33 @@ import {
   CardTitle,
 } from "@/components/ui/card";
 
-export function EnvelopeCard({ envelope }: { envelope: Envelope }) {
+interface Signal {
+  id: string;
+  receiver: string;
+  target: string;
+  status: string;
+}
+
+export function SignalCard({ signal }: { signal: Signal }) {
   return (
-    <Card className="bg-[#0f0f14] border-[#1e293b]">
+    <Card>
       <CardHeader className="pb-2">
         <CardTitle className="flex items-center gap-2 text-sm font-mono">
-          <span className="text-slate-400">envelope</span>
-          <span className="text-blue-400">{envelope.id}</span>
+          <span className="text-font/60">signal</span>
+          <span className="text-primary">{signal.id}</span>
         </CardTitle>
         <CardDescription>
-          {envelope.env.action} → {envelope.metadata?.receiver}
+          {signal.receiver} → {signal.target}
         </CardDescription>
       </CardHeader>
       <CardContent className="space-y-2">
         <div className="font-mono text-xs">
-          <span className="text-slate-500">action: </span>
-          <span className="text-green-400">{envelope.env.action}</span>
+          <span className="text-font/40">receiver: </span>
+          <span className="text-tertiary">{signal.receiver}</span>
         </div>
         <div className="font-mono text-xs">
-          <span className="text-slate-500">inputs: </span>
-          <span className="text-amber-400">
-            {JSON.stringify(envelope.env.inputs)}
-          </span>
-        </div>
-        <div className="font-mono text-xs">
-          <span className="text-slate-500">status: </span>
-          <StatusBadge status={envelope.payload.status} />
+          <span className="text-font/40">status: </span>
+          <StatusBadge status={signal.status} />
         </div>
       </CardContent>
     </Card>
@@ -108,30 +164,31 @@ export function EnvelopeCard({ envelope }: { envelope: Envelope }) {
 }
 ```
 
-### Tabs (Agent Selection)
+`Card` already resolves to the `foreground` surface via `--color-card`. Do not
+re-skin it with a background utility.
+
+### Tabs
 
 ```tsx
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 
-export function AgentTabs({ agents }: { agents: Agent[] }) {
+interface Actor { id: string; name: string; status: string }
+
+export function ActorTabs({ actors }: { actors: Actor[] }) {
   return (
-    <Tabs defaultValue={agents[0]?.id} className="w-full">
-      <TabsList className="bg-[#0f0f14] border border-[#1e293b]">
-        {agents.map(agent => (
-          <TabsTrigger
-            key={agent.id}
-            value={agent.id}
-            className="data-[state=active]:bg-[#1e293b] data-[state=active]:text-white"
-          >
-            <StatusDot status={agent.status} />
-            <span className="ml-2">{agent.name}</span>
+    <Tabs defaultValue={actors[0]?.id} className="w-full">
+      <TabsList>
+        {actors.map(actor => (
+          <TabsTrigger key={actor.id} value={actor.id}>
+            <StatusDot status={actor.status} />
+            <span className="ml-2">{actor.name}</span>
           </TabsTrigger>
         ))}
       </TabsList>
 
-      {agents.map(agent => (
-        <TabsContent key={agent.id} value={agent.id} className="mt-4">
-          <AgentContent agent={agent} />
+      {actors.map(actor => (
+        <TabsContent key={actor.id} value={actor.id} className="mt-4">
+          <ActorContent actor={actor} />
         </TabsContent>
       ))}
     </Tabs>
@@ -139,26 +196,26 @@ export function AgentTabs({ agents }: { agents: Agent[] }) {
 }
 ```
 
-### Badge (Status Indicators)
+### Badge
+
+Status color comes from the 5 invariants plus the 3 brand tokens — never from a
+Tailwind palette ramp.
 
 ```tsx
 import { Badge } from "@/components/ui/badge";
 
-const statusColors = {
-  ready: "bg-green-500/20 text-green-400 border-green-500/30",
-  resolved: "bg-green-500/20 text-green-400 border-green-500/30",
-  pending: "bg-amber-500/20 text-amber-400 border-amber-500/30",
-  waiting: "bg-amber-500/20 text-amber-400 border-amber-500/30",
-  idle: "bg-slate-500/20 text-slate-400 border-slate-500/30",
-  error: "bg-red-500/20 text-red-400 border-red-500/30",
-  rejected: "bg-red-500/20 text-red-400 border-red-500/30",
+const statusClasses = {
+  resolved: "bg-success/20 text-success",
+  pending:  "bg-secondary/20 text-secondary",
+  idle:     "bg-font/10 text-font/60",
+  error:    "bg-destructive/20 text-destructive",
 };
 
 export function StatusBadge({ status }: { status: string }) {
   return (
     <Badge
       variant="outline"
-      className={statusColors[status as keyof typeof statusColors] || statusColors.idle}
+      className={statusClasses[status as keyof typeof statusClasses] ?? statusClasses.idle}
     >
       {status}
     </Badge>
@@ -166,43 +223,41 @@ export function StatusBadge({ status }: { status: string }) {
 }
 ```
 
-### Button Variants
+### Button
+
+The repo's `button.tsx` ships **6 variants** — `default` · `outline` ·
+`secondary` · `ghost` · `destructive` · `link` — and **8 sizes** — `default` ·
+`xs` · `sm` · `lg` · `icon` · `icon-xs` · `icon-sm` · `icon-lg`. There is no
+`primary` variant name; `default` already means `bg-primary text-primary-foreground`.
 
 ```tsx
 import { Button } from "@/components/ui/button";
+import { ChevronRight } from "lucide-react";
 
-// Primary action
-<Button className="bg-blue-600 hover:bg-blue-700">
-  Send Envelope
-</Button>
-
-// Secondary action
-<Button variant="outline" className="border-[#1e293b] hover:bg-[#1e293b]">
-  Cancel
-</Button>
-
-// Destructive
-<Button variant="destructive">
-  Reject
-</Button>
-
-// Ghost (icon buttons)
+<Button>Send signal</Button>                    {/* default = brand fill */}
+<Button variant="outline">Cancel</Button>
+<Button variant="secondary">Save draft</Button>
+<Button variant="destructive">Reject</Button>
 <Button variant="ghost" size="icon">
-  <ChevronRight className="h-4 w-4" />
+  <ChevronRight />
 </Button>
 ```
 
-### ScrollArea (Lists)
+Do not pass a background class to override the variant — that is how a palette
+class gets reintroduced. Add a variant to the `cva` block instead.
+
+### ScrollArea
 
 ```tsx
 import { ScrollArea } from "@/components/ui/scroll-area";
+import { SignalCard } from "./SignalCard";
 
-export function EnvelopeList({ envelopes }: { envelopes: Envelope[] }) {
+export function SignalList({ signals }: { signals: Signal[] }) {
   return (
     <ScrollArea className="h-[400px] pr-4">
       <div className="space-y-3">
-        {envelopes.map(env => (
-          <EnvelopeCard key={env.id} envelope={env} />
+        {signals.map(s => (
+          <SignalCard key={s.id} signal={s} />
         ))}
       </div>
     </ScrollArea>
@@ -210,7 +265,7 @@ export function EnvelopeList({ envelopes }: { envelopes: Envelope[] }) {
 }
 ```
 
-### Tooltip (Hover Info)
+### Tooltip
 
 ```tsx
 import {
@@ -220,11 +275,11 @@ import {
   TooltipTrigger,
 } from "@/components/ui/tooltip";
 
-export function EnvelopeId({ id, full }: { id: string; full: string }) {
+export function SignalId({ id, full }: { id: string; full: string }) {
   return (
     <TooltipProvider>
       <Tooltip>
-        <TooltipTrigger className="font-mono text-blue-400 cursor-help">
+        <TooltipTrigger className="font-mono text-primary cursor-help">
           {id}
         </TooltipTrigger>
         <TooltipContent>
@@ -236,7 +291,7 @@ export function EnvelopeId({ id, full }: { id: string; full: string }) {
 }
 ```
 
-### Accordion (Collapsible Logic)
+### Accordion
 
 ```tsx
 import {
@@ -246,16 +301,14 @@ import {
   AccordionTrigger,
 } from "@/components/ui/accordion";
 
-export function LogicViewer({ code }: { code: string }) {
+export function ConfigViewer({ code }: { code: string }) {
   return (
-    <Accordion type="single" collapsible defaultValue="logic">
-      <AccordionItem value="logic" className="border-[#1e293b]">
-        <AccordionTrigger className="text-sm">
-          Agent Logic
-        </AccordionTrigger>
+    <Accordion type="single" collapsible defaultValue="config">
+      <AccordionItem value="config">
+        <AccordionTrigger className="text-sm">Step config</AccordionTrigger>
         <AccordionContent>
-          <pre className="p-4 bg-[#0a0a0f] rounded font-mono text-xs overflow-x-auto">
-            <code className="text-slate-300">{code}</code>
+          <pre className="p-4 bg-background rounded font-mono text-xs overflow-x-auto">
+            <code className="text-font/80">{code}</code>
           </pre>
         </AccordionContent>
       </AccordionItem>
@@ -269,21 +322,18 @@ export function LogicViewer({ code }: { code: string }) {
 ### Status Dot
 
 ```tsx
-const dotColors = {
-  ready: "bg-green-500",
-  resolved: "bg-green-500",
-  pending: "bg-amber-500 animate-pulse",
-  waiting: "bg-amber-500 animate-pulse",
-  idle: "bg-slate-500",
-  error: "bg-red-500",
-  rejected: "bg-red-500",
+const dotClasses = {
+  resolved: "bg-success",
+  pending:  "bg-secondary animate-pulse",
+  idle:     "bg-font/40",
+  error:    "bg-destructive",
 };
 
 export function StatusDot({ status }: { status: string }) {
   return (
     <span
       className={`inline-block w-2 h-2 rounded-full ${
-        dotColors[status as keyof typeof dotColors] || dotColors.idle
+        dotClasses[status as keyof typeof dotClasses] ?? dotClasses.idle
       }`}
     />
   );
@@ -293,24 +343,20 @@ export function StatusDot({ status }: { status: string }) {
 ### Panel Header
 
 ```tsx
-export function PanelHeader({
-  title,
-  count,
-  children,
-}: {
+import { Badge } from "@/components/ui/badge";
+
+interface PanelHeaderProps {
   title: string;
   count?: number;
   children?: React.ReactNode;
-}) {
+}
+
+export function PanelHeader({ title, count, children }: PanelHeaderProps) {
   return (
     <div className="flex items-center justify-between mb-4">
       <div className="flex items-center gap-2">
-        <h3 className="text-sm font-medium text-slate-300">{title}</h3>
-        {count !== undefined && (
-          <Badge variant="secondary" className="bg-[#1e293b]">
-            {count}
-          </Badge>
-        )}
+        <h3 className="text-sm font-medium text-font/80">{title}</h3>
+        {count !== undefined && <Badge variant="secondary">{count}</Badge>}
       </div>
       {children}
     </div>
@@ -321,18 +367,19 @@ export function PanelHeader({
 ### Code Block
 
 ```tsx
-export function CodeBlock({
-  code,
-  language = "typescript",
-}: {
+import { Card, CardContent } from "@/components/ui/card";
+
+interface CodeBlockProps {
   code: string;
   language?: string;
-}) {
+}
+
+export function CodeBlock({ code, language = "typescript" }: CodeBlockProps) {
   return (
-    <Card className="bg-[#0a0a0f] border-[#1e293b]">
+    <Card data-language={language}>
       <CardContent className="p-0">
         <pre className="p-4 overflow-x-auto">
-          <code className="font-mono text-xs text-slate-300 whitespace-pre">
+          <code className="font-mono text-xs text-font/80 whitespace-pre">
             {code}
           </code>
         </pre>
@@ -344,31 +391,39 @@ export function CodeBlock({
 
 ## Adding New Components
 
-To add a new shadcn component:
-
 ```bash
-# From project root
-bunx shadcn@latest add [component-name]
-
-# Examples
+# from one.ie/web (components.json lives there)
 bunx shadcn@latest add sheet
 bunx shadcn@latest add command
 bunx shadcn@latest add popover
 ```
 
+**Always run the token pass immediately after.** The CLI writes upstream defaults
+that assume Tailwind's palette exists:
+
+```bash
+grep -nE 'text-foreground|#[0-9a-fA-F]{3,8}|(bg|text|border)-(zinc|slate|gray|neutral|red|green|blue|amber)-[0-9]' \
+  src/components/ui/<new>.tsx
+```
+
+Every hit is a fix: `text-foreground` → `text-font`; a palette class → a token
+utility or an alias from the table above; a hex → a token. The `design-check.sh`
+PostToolUse hook catches these on your next edit of the file, but the CLI writes
+the file without going through the hook — so sweep it yourself.
+
 ## Customization Patterns
 
 ### Extending Button
 
 ```tsx
-// src/components/ui/button.tsx - add variant
+// src/components/ui/button.tsx — add to the existing cva variants block
 const buttonVariants = cva(
   "...",
   {
     variants: {
       variant: {
-        // ... existing variants
-        envelope: "bg-blue-600/20 text-blue-400 border border-blue-600/30 hover:bg-blue-600/30",
+        // ... default | outline | secondary | ghost | destructive | link
+        brand: "bg-tertiary text-on-tertiary hover:bg-tertiary/80",
       },
     },
   }
@@ -378,20 +433,17 @@ const buttonVariants = cva(
 ### Custom Card Variant
 
 ```tsx
-export function EnvelopeCardVariant({
-  children,
-  isNested,
-}: {
+import { Card } from "@/components/ui/card";
+import { cn } from "@/lib/utils";
+
+interface NestedCardProps {
   children: React.ReactNode;
   isNested?: boolean;
-}) {
+}
+
+export function NestedCard({ children, isNested }: NestedCardProps) {
   return (
-    <Card
-      className={cn(
-        "bg-[#0f0f14] border-[#1e293b]",
-        isNested && "ml-4 border-l-2 border-l-blue-500/30"
-      )}
-    >
+    <Card className={cn(isNested && "ml-4 border-l-2 border-l-primary")}>
       {children}
     </Card>
   );
@@ -403,20 +455,24 @@ export function EnvelopeCardVariant({
 ### Two-Panel Layout
 
 ```tsx
-export function WorkspaceLayout() {
+import { ScrollArea } from "@/components/ui/scroll-area";
+
+export function WorkspaceLayout({ actors, signals }: { actors: Actor[]; signals: Signal[] }) {
   return (
-    <div className="h-screen flex flex-col bg-[#0a0a0f]">
-      {/* Top Panel - Agent Tabs */}
-      <div className="flex-none h-[40%] border-b border-[#1e293b] p-4">
-        <AgentTabs />
+    <div className="h-screen flex flex-col bg-background">
+      <div
+        className="flex-none h-[40%] border-b p-4"
+        style={{ borderColor: 'var(--color-border)' }}
+      >
+        <ActorTabs actors={actors} />
       </div>
 
-      {/* Bottom Panel - Envelopes & Logic */}
       <div className="flex-1 overflow-hidden p-4">
         <ScrollArea className="h-full">
-          <EnvelopeList />
+          <SignalList signals={signals} />
         </ScrollArea>
       </div>
+      {/* ActorTabs / SignalList as defined above */}
     </div>
   );
 }
@@ -425,48 +481,36 @@ export function WorkspaceLayout() {
 ### Grid Layout
 
 ```tsx
-export function AgentGrid({ agents }: { agents: Agent[] }) {
+import { ActorCard } from "./ActorCard";
+
+export function ActorGrid({ actors }: { actors: Actor[] }) {
   return (
     <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-      {agents.map(agent => (
-        <AgentCard key={agent.id} agent={agent} />
+      {actors.map(actor => (
+        <ActorCard key={actor.id} actor={actor} />
       ))}
     </div>
   );
 }
 ```
 
-## Utils
-
-The project uses `cn()` utility for class merging:
-
-```tsx
-// src/lib/utils.ts
-import { clsx, type ClassValue } from "clsx";
-import { twMerge } from "tailwind-merge";
-
-export function cn(...inputs: ClassValue[]) {
-  return twMerge(clsx(inputs));
-}
-
-// Usage
-<div className={cn(
-  "base-classes",
-  isActive && "active-classes",
-  className
-)} />
-```
-
 ## Best Practices
 
-1. **Use semantic colors**: Status colors for state, not random colors
-2. **Consistent spacing**: Use Tailwind's spacing scale (4, 8, 12, 16...)
-3. **Dark-first**: Design for dark theme, colors should work on `#0a0a0f`
-4. **Monospace for data**: Use `font-mono` for IDs, JSON, code
-5. **Subtle borders**: Use `border-[#1e293b]` for separation
-6. **Animate pending**: Use `animate-pulse` for pending states
+1. **Let the primitive keep its surface**: `Card` already resolves to `foreground`
+   through `--color-card`. Adding `bg-*` on top fights the alias.
+2. **`text-font`, never `text-foreground`**: the one shadcn name the alias table
+   cannot rescue.
+3. **Contrast labels on brand fills**: `text-on-primary` in ONE code,
+   `text-primary-foreground` inside a CLI-generated primitive — both resolve to
+   the same computed color.
+4. **Variants over overrides**: extend the `cva` block rather than passing a
+   className that re-colors the button.
+5. **Sweep after `shadcn add`**: the CLI bypasses the design hook.
+6. **Monospace for data**: `font-mono` for IDs, JSON, code.
+7. **Icons from lucide only**: via `<Icon>` / `<IconBadge>`, never inline SVG in
+   a React component.
 
 ---
 
-**Version**: 1.0.0
-**Tech**: shadcn/ui, Tailwind CSS 4, Radix UI
+**Tech**: shadcn/ui (`style: radix-nova`) · `radix-ui` ^1.4.3 · Tailwind CSS 4 · React 19
+**Tree**: `one.ie/web` — for `template/site` use `template:shadcn`