@adrelle/design-system 0.0.0-stage → 3.2.1

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# @adrelle/design-system
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A premium, state-of-the-art CSS-first Design System built for modern SaaS applications. Compatible with vanilla HTML/CSS and fully integrated with Tailwind CSS v4.
+
+---
+
+## 🚀 Installation
+
+Install the package via your preferred package manager:
+
+```bash
+npm install @adrelle/design-system
+# or
+yarn add @adrelle/design-system
+# or
+pnpm add @adrelle/design-system
+```
+
+---
+
+## 🛠️ Usage
+
+### 1. Vanilla CSS Integration
+Import the clean CSS bundle into your main stylesheet:
+
+```css
+@import "@adrelle/design-system";
+```
+
+### 2. Tailwind CSS v4 Integration
+If your project is built with Tailwind CSS v4, import Tailwind and then load our theme wrapper stylesheet:
+
+```css
+@import "tailwindcss";
+
+/* Imports all components and links theme variables to Tailwind v4 */
+@import "@adrelle/design-system/app.css";
+```
+
+#### Theming & Dark Mode:
+Theme switching is driven entirely by CSS variables. Toggling the `.dark` class on `:root` (`<html>`) switches all semantic variables (`--background`, `--foreground`, `--card`, `--border`, `--primary`, etc.) automatically without needing inline conditional classes.
+
+#### Disabling Dark Mode (Light Mode Only):
+If you want to disable dark mode entirely and force your website to stay in light mode (even if the user's OS prefers dark mode), simply add the `light` class to your root `<html>` element:
+
+```html
+<html class="light">
+```
+This disables the built-in prefers-color-scheme media query and keeps the light-mode variables active.
+
+---
+
+## 🎨 Theme Variables & Customization
+
+The design system is engineered for modern B2B SaaS interfaces. It exposes slate neutrals, sky/ocean brand blue (`#0284C7` anchor), micro-elevations (`shadow-xs`), and strict mathematical corner radii:
+
+```css
+:root {
+  --primary: var(--sky-700);        /* #0369a1 - Primary brand action (Light) */
+  --primary-hover: var(--sky-800);  /* #075985 - Hover state */
+  --primary-active: var(--sky-900); /* #0c4a6e - Active state */
+  --primary-foreground: #fff;
+  --radius-xl: 0.75rem;             /* Page containers, cards, modals */
+  --radius-lg: 0.5rem;              /* Action buttons, form inputs */
+  --radius-md: 0.375rem;            /* Badges, table chips, segmented tabs */
+}
+
+.dark {
+  --background: #020617;            /* Deep slate-950 canvas (no pitch black) */
+  --card: #0f172a;                  /* Slate-900 surface */
+  --border: #1e293b;                /* Crisp 1px border */
+  --primary: var(--sky-300);        /* #7dd3fc - Accessible high-contrast primary (Dark) */
+  --primary-foreground: #020617;
+}
+```
+![Design Tokens](./src/assets/design-tokens.png)
+
+### Core Semantic Tokens Available:
+* `--background` / `--foreground`: Base canvas (`slate-50` / `slate-950`) & text
+* `--card` / `--card-nested`: Surfaces & cluster wells (`slate-50/70` / `slate-800/40`)
+* `--primary` / `--primary-hover` / `--primary-active` / `--primary-foreground`: Brand actions (Sky scale anchored on `#0284C7`)
+* `--primary-tint` / `--primary-border`: Subtle brand highlighting
+* `--secondary` / `--secondary-hover` / `--secondary-foreground`: Secondary actions
+* `--accent` / `--accent-hover` / `--accent-foreground`: Interactive highlights
+* `--neutral` / `--neutral-hover` / `--neutral-foreground`: Muted helpers and subtle backgrounds
+* `--border`: Structural container borders (`slate-200` / `slate-800`)
+* `--success` / `--warning` / `--info` / `--danger`: High-contrast semantic indicators (Emerald, Amber, Sky, Rose)
+* `--radius-xl` / `--radius-lg` / `--radius-md` / `--radius-full`: Geometry scale
+* `--shadow-xs` / `--shadow-lg` / `--shadow-xl`: Crisp micro-elevation hierarchy
+
+---
+
+## ⚡ Component & Layout Reference
+
+The package includes pre-styled, accessibility-compliant CSS components with zero AI artifacts (no purple orbs, no decorative emojis, no indiscriminate pill badges):
+
+- **`.button`**: Standardized, transition-ready buttons with `rounded-lg` and `shadow-xs`. Variants: `.button-primary`, `.button-secondary`, `.button-outline`, `.button-destructive`, `.button-ghost`, `.button-icon`, and `.button-link`. Sizes: `.button-sm`, `.button-lg`.
+- **`.segmented-switcher` & `.segmented-tab`**: Segmented view switchers.
+- **`.card`**: 5-level container rhythm (`.card`, `.card-well`, `.card-tile`, `.icon-box`, `.stat-value`, `.stat-change`).
+- **`.table-container` & `.table`**: Tabular ledgers with sticky headers, `.table-numeric` right-aligned monospace numbers, and `.table-footer` pagination.
+- **`.form-group`**: Form elements:
+  * `.form-input` / `.form-select` / `.form-textarea`: Form control fields with brand focus ring (`--primary`)
+  * `.form-search`: Search input with inline icon positioning
+  * `.form-error-banner`: Structured validation callout banner
+  * `.form-file` / `.form-range` / `.form-checkbox` / `.form-radio`: Fully styled input components
+- **`.badge`**: Rectangular status badges (`rounded-md uppercase tracking-wider`) with `.badge-dot` pulsing indicators and `.badge-mono` numeric chips. Never pill-shaped.
+- **`.alert`**: Semantic feedback containers with 1px tinted borders (`.alert-success`, `.alert-warning`, `.alert-danger`, `.alert-info`).
+- **`.dialog` & `.drawer`**: 5-region modal dialogs (`shadow-lg`, backdrop blur) and slide-over preview drawers (`shadow-xl`).
+- **`.sidebar` & `.navbar`**: Collapsible sidebars with subtle blue tint active highlighting (`.sidebar-item.active`) and `.telemetry-pulse` operational indicators.
+
+---
+
+## 🔧 Local Development & Sandbox (Vue Playground)
+
+If you are contributing to this design system project:
+
+1. Clone the repository and install local dev dependencies:
+   ```bash
+   npm install
+   ```
+2. Start the Vue sandbox to preview components:
+   ```bash
+   npm run dev
+   ```
+3. Compile the production bundles:
+   ```bash
+   npm run build
+   ```

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@adrelle/design-system",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "private": false,
+  "version": "3.2.1",
+  "type": "module",
+  "main": "src/css/index.css",
+  "files": [
+    "src/css"
+  ],
+  "exports": {
+    ".": "./src/css/index.css",
+    "./colors.css": "./src/css/theme/colors.css",
+    "./app.css": "./src/css/app.css"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.3.1",
+    "lightningcss": "^1.32.0",
+    "tailwindcss": "^4.3.1",
+    "vue": "^3.5.38"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.7",
+    "stylelint": "^17.14.1",
+    "stylelint-config-standard": "^40.0.0",
+    "vite": "^8.1.0"
+  }
+}

package/src/css/app.css

@@ -0,0 +1,90 @@
+@import "./index.css";
+
+@theme inline {
+  --font-sans:
+    Inter, ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji",
+    "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+  --font-mono:
+    "JetBrains Mono", ui-monospace, sfmono-regular, menlo, monaco, consolas,
+    "Liberation Mono", "Courier New", monospace;
+  --radius-xl: var(--radius-xl);
+  --radius-lg: var(--radius-lg);
+  --radius-md: var(--radius-md);
+  --radius-sm: var(--radius-sm);
+  --radius-xs: var(--radius-xs);
+  --color-black: var(--black);
+  --color-white: var(--white);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-nested: var(--card-nested);
+  --color-card-foreground: var(--foreground);
+  --color-primary: var(--primary);
+  --color-primary-hover: var(--primary-hover);
+  --color-primary-active: var(--primary-active);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary-tint: var(--primary-tint);
+  --color-primary-border: var(--primary-border);
+  --color-secondary: var(--secondary);
+  --color-secondary-hover: var(--secondary-hover);
+  --color-secondary-active: var(--secondary-active);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary-border: var(--secondary-border);
+  --color-accent: var(--accent);
+  --color-accent-hover: var(--accent-hover);
+  --color-accent-active: var(--accent-active);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-neutral: var(--neutral);
+  --color-neutral-hover: var(--neutral-hover);
+  --color-neutral-foreground: var(--neutral-foreground);
+  --color-border: var(--border);
+  --color-success: var(--success);
+  --color-success-hover: var(--success-hover);
+  --color-success-foreground: var(--success-foreground);
+  --color-success-tint: var(--success-tint);
+  --color-success-border: var(--success-border);
+  --color-warning: var(--warning);
+  --color-warning-hover: var(--warning-hover);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-warning-tint: var(--warning-tint);
+  --color-warning-border: var(--warning-border);
+  --color-info: var(--info);
+  --color-info-hover: var(--info-hover);
+  --color-info-foreground: var(--info-foreground);
+  --color-info-tint: var(--info-tint);
+  --color-info-border: var(--info-border);
+  --color-danger: var(--danger);
+  --color-danger-hover: var(--danger-hover);
+  --color-danger-foreground: var(--danger-foreground);
+  --color-danger-tint: var(--danger-tint);
+  --color-danger-border: var(--danger-border);
+}
+
+/* Utility classes that rely on Tailwind rules can remain here or inside the components */
+@utility muted {
+  color: var(--neutral-foreground);
+}
+
+@utility container-layout {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+}
+
+@layer base {
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
+    border-color: var(--color-gray-200, currentColor);
+  }
+
+  * {
+    @apply border-border outline-primary/50;
+  }
+
+  body {
+    @apply bg-background text-foreground;
+  }
+}

package/src/css/components/alert.css

@@ -0,0 +1,54 @@
+.alert {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.75rem;
+  padding: 0.875rem 1rem;
+  border-radius: var(--radius-lg, 0.5rem);
+  border: 1px solid var(--border);
+  background-color: var(--neutral);
+  color: var(--foreground);
+  font-size: 0.75rem;
+  line-height: 1.4;
+  box-shadow: var(--shadow-xs);
+}
+
+.alert-content {
+  flex: 1;
+}
+
+.alert-title {
+  font-weight: 600;
+  font-size: 0.75rem;
+  margin-bottom: 0.125rem;
+}
+
+.alert-description {
+  font-size: 0.6875rem;
+  opacity: 0.9;
+}
+
+/* Semantic Feedback Alerts (frontend-core tokens) */
+.alert-success {
+  background-color: var(--success-tint);
+  border-color: var(--success-border);
+  color: var(--success);
+}
+
+.alert-warning {
+  background-color: var(--warning-tint);
+  border-color: var(--warning-border);
+  color: var(--warning);
+}
+
+.alert-danger {
+  background-color: var(--danger-tint);
+  border-color: var(--danger-border);
+  color: var(--danger);
+}
+
+.alert-info {
+  background-color: var(--info-tint);
+  border-color: var(--info-border);
+  color: var(--info);
+}
+

package/src/css/components/badge.css

@@ -0,0 +1,98 @@
+/* Rectangular Badge Hierarchy (frontend-core: rounded-md, uppercase, tracking-wider) */
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+  border-radius: var(--radius-md, 0.375rem);
+  padding: 0.125rem 0.5rem;
+  font-size: 0.625rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  line-height: 1rem;
+  border: 1px solid var(--border);
+  user-select: none;
+  background-color: var(--neutral);
+  color: var(--neutral-foreground);
+  box-shadow: var(--shadow-xs);
+  white-space: nowrap;
+}
+
+/* Success / Active Badge */
+.badge-success {
+  background-color: var(--success-tint);
+  color: var(--success);
+  border-color: var(--success-border);
+}
+
+/* Warning / Pending Badge */
+.badge-warning {
+  background-color: var(--warning-tint);
+  color: var(--warning);
+  border-color: var(--warning-border);
+}
+
+/* Danger / Destructive Badge */
+.badge-danger,
+.badge-destructive {
+  background-color: var(--danger-tint);
+  color: var(--danger);
+  border-color: var(--danger-border);
+}
+
+/* Info / Telemetry Badge */
+.badge-info {
+  background-color: var(--info-tint);
+  color: var(--info);
+  border-color: var(--info-border);
+}
+
+/* Neutral Badge */
+.badge-neutral {
+  background-color: var(--neutral);
+  color: var(--neutral-foreground);
+  border-color: var(--border);
+}
+
+/* Monospace Numeric / Timestamp Chip */
+.badge-mono {
+  font-family: var(--font-mono);
+  font-feature-settings: "tnum" 1;
+}
+
+/* Circular Status Indicator Pulse Dot (strictly rounded-full) */
+.badge-dot {
+  width: 0.375rem;
+  height: 0.375rem;
+  border-radius: var(--radius-full, 9999px);
+  animation: badge-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+  flex-shrink: 0;
+  background-color: currentColor;
+}
+
+.badge-dot-success {
+  background-color: #10b981;
+}
+
+.badge-dot-warning {
+  background-color: #f59e0b;
+}
+
+.badge-dot-danger {
+  background-color: #f43f5e;
+}
+
+.badge-dot-info {
+  background-color: #3b82f6;
+}
+
+.badge-dot-neutral {
+  background-color: #94a3b8;
+}
+
+@keyframes badge-pulse {
+  50% {
+    opacity: 0.4;
+  }
+}
+

package/src/css/components/breadcrumb.css

@@ -0,0 +1,39 @@
+.breadcrumb {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.375rem;
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  font-size: 0.75rem;
+}
+
+.breadcrumb-item {
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
+  color: var(--neutral-foreground);
+}
+
+.breadcrumb-item a {
+  color: var(--neutral-foreground);
+  text-decoration: none;
+  transition: color 0.15s ease;
+}
+
+.breadcrumb-item a:hover {
+  color: var(--foreground);
+}
+
+.breadcrumb-separator {
+  color: var(--neutral-foreground);
+  user-select: none;
+  opacity: 0.6;
+}
+
+.breadcrumb-item.active {
+  color: var(--foreground);
+  font-weight: 600;
+}
+