@codelitdev/design-system 0.1.0-alpha.0 → 0.1.0-alpha.2

package/README.md

@@ -9,11 +9,19 @@ the preset and keep their own shadcn components.
 ## Install
 
 Published to npm as a public package. The current release line is a prerelease
-under the `alpha` dist-tag:
+under the `alpha` dist-tag.
+
+> [!WARNING]
+> **`latest` currently also points at `0.1.0-alpha.0`.** npm always sets
+> `latest` on a package's first-ever publish, regardless of `--tag` — this is
+> unavoidable until a real stable version is cut, at which point publishing it
+> moves `latest` forward automatically. Until then, **always pin the exact
+> version** — do not `npm install @codelitdev/design-system` bare, and do not
+> use a caret/tilde range (`^0.1.0-alpha.0` would still resolve to a
+> prerelease, which is at least explicit — but a bare install with no version
+> silently means "whatever `latest` is," which right now is this alpha).
 
 ```sh
-npm install @codelitdev/design-system@alpha
-# or a specific version
 npm install @codelitdev/design-system@0.1.0-alpha.0
 ```
 
@@ -38,17 +46,86 @@ module.exports = {
 };
 ```
 
-3. Scope the product on your root layout:
+3. Scope the product on the **`<html>`** element (not `<body>`):
 ```tsx
-<body data-product="sendlit">  {/* courselit | medialit | sendlit | frontlit, omit for CodeLit amber */}
+<html data-product="sendlit">  {/* courselit | medialit | sendlit | frontlit, omit for CodeLit amber */}
 ```
+> [!IMPORTANT]
+> Put `data-product` on `<html>`, not `<body>`. The product scope only overrides
+> `--primary`/`--ring`; any token you alias at `:root` that references `--primary`
+> (e.g. shadcn's `--sidebar-primary: var(--primary)`) resolves that `var()` **at the
+> declaring element**. If the override sits on `<body>` (a child of `:root`), those
+> `:root` aliases freeze to the base amber and never pick up the product accent —
+> while direct `bg-primary` utilities still turn green, producing a confusing split.
 
 4. Fonts: load Hanken Grotesk + Spline Sans Mono via `next/font/google` (or your framework's font loader), mapped to `--font-sans` / `--font-mono`.
 
-5. Components in `src/components/` (Button, IconButton, Badge, Card, Tabs, Dialog, Toast, Tooltip, Checkbox, Input, Radio, Select, Switch) are plain React + CSS classes (`components.css`), not Radix-based — treat them as reference/fallback. For shadcn's Radix-based primitives (Select, Dialog, Tabs, Tooltip), keep your app's existing shadcn components and port the visual deltas from `components.css` into their CVA variants instead of importing these directly.
+5. **Components — install from the shadcn registry** (see [Components](#components-shadcn-registry) below). These are real shadcn/Radix components styled to the design system, so your app's buttons/badges/cards *are* the DS's — no hand-porting. The plain-React `src/components/` classes (`components.css`) remain as visual reference only.
 
 6. Logos: `@codelitdev/design-system/assets/logo-<product>.svg`.
 
+## Components (shadcn registry)
+
+The design system ships its components as a **shadcn registry** so every product
+installs the *same* styled components (buttons, badges, cards, …) via the shadcn
+CLI — keeping all four apps on one component layer instead of each re-styling its
+own. They're standard shadcn/Radix components; they pull their look from the DS
+tokens, so make sure `@codelitdev/design-system/styles.css` is imported (above).
+
+Add the registry namespace to your app's `components.json`:
+
+```jsonc
+{
+  "registries": {
+    "@codelit": "https://raw.githubusercontent.com/codelitdev/design-system/main/public/r/{name}.json"
+  }
+}
+```
+
+Then install components like any other shadcn component:
+
+```sh
+npx shadcn@latest add @codelit/button @codelit/badge @codelit/card
+```
+
+Or install a single component directly by URL, no config:
+
+```sh
+npx shadcn@latest add https://raw.githubusercontent.com/codelitdev/design-system/main/public/r/button.json
+```
+
+### Available components
+
+| Component | Notes |
+|---|---|
+| `button` | `primary` / `secondary` / `outline` / `ghost` / **`soft`** / `destructive`; `sm` `md` `lg` (30/36/42px) |
+| `icon-button` | Square icon-only; `ghost` / `outline`; `sm` `md` |
+| `badge` | `default` / `neutral` / `success` / `warning` / `destructive` / `outline`; `dot` prop |
+| `card` | + `CardHeader` `CardTitle` `CardDescription` `CardContent` `CardFooter` |
+| `input` | Accent-wash focus ring; `aria-invalid` → destructive |
+| `textarea` | Multiline form of `input` |
+| `label` | 13px semibold field label |
+| `checkbox` | 18px, 5px radius, accent fill when checked |
+| `radio-group` | + `RadioGroupItem` |
+| `switch` | 36×21 track, accent when on |
+| `select` | Trigger matches `input`; token-styled popover |
+| `tabs` | Segmented; active trigger lifts onto a card surface |
+| `dialog` | Warm scrim, 16px radius; full Radix parts |
+| `tooltip` | Dark chip; `TooltipProvider` included |
+| `toast` | Presentational card (`default`/`success`/`destructive`) — drive with your own queue |
+
+Install everything at once:
+
+```sh
+npx shadcn@latest add @codelit/button @codelit/icon-button @codelit/badge @codelit/card \
+  @codelit/input @codelit/textarea @codelit/label @codelit/checkbox @codelit/radio-group \
+  @codelit/switch @codelit/select @codelit/tabs @codelit/dialog @codelit/tooltip @codelit/toast
+```
+
+**Maintainers:** component sources live in `registry/codelit/ui/`. After changing
+one, rebuild the served JSON with `pnpm registry:build` (→ `public/r/*.json`) and
+commit it — the raw-URL install serves those committed files.
+
 ## Publishing
 
 Prereleases go under the `alpha` dist-tag so a plain `npm install` never grabs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codelitdev/design-system",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "description": "Shared CodeLit design tokens, Tailwind preset, and React primitives for CourseLit, MediaLit, SendLit, and FrontLit.",
   "license": "Apache-2.0",
   "author": "CodeLit",
@@ -15,7 +15,8 @@
   "main": "src/index.ts",
   "types": "src/index.ts",
   "scripts": {
-    "release:alpha": "npm publish --tag alpha"
+    "release:alpha": "npm publish --tag alpha",
+    "registry:build": "shadcn build"
   },
   "exports": {
     ".": "./src/index.ts",
@@ -39,6 +40,7 @@
   ],
   "devDependencies": {
     "@types/react": "^19.2.17",
-    "lucide-react": "^0.544.0"
+    "lucide-react": "^0.544.0",
+    "shadcn": "^4.14.0"
   }
 }

package/src/tokens/typography.css

@@ -29,7 +29,12 @@ body {
   -webkit-font-smoothing: antialiased;
 }
 
-a { color: var(--primary); text-decoration: none; }
-a:hover { color: var(--primary-hover); text-decoration: underline; }
+/* No global `a` styling — this stylesheet is imported by full apps where bare
+   <a>/<Link> are routinely used for navigation and clickable cards, and a
+   blanket hover-underline breaks that UX. Opt in explicitly with .cl-link for
+   inline text links (prose, footnotes, etc.); interactive apps should use the
+   Button `link` variant / registry Button instead. */
+.cl-link { color: var(--primary); text-decoration: none; }
+.cl-link:hover { color: var(--primary-hover); text-decoration: underline; }
 
 code, kbd, pre { font: var(--text-code); }