@teseor/css 2.5.0 → 2.5.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Teseor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,102 +1,150 @@
 # @teseor/css
 
-CSS components library with design tokens and standalone support.
+CSS components library with design tokens, 8px grid rhythm, and standalone component support.
 
 ## Installation
 
 ```bash
 npm install @teseor/css
+# or
+pnpm add @teseor/css
+```
+
+### CDN
+
+Use directly without a build step:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@teseor/css/dist/index.css">
+<!-- or -->
+<link rel="stylesheet" href="https://unpkg.com/@teseor/css/dist/index.css">
 ```
 
 ## Usage
 
-### Option 1: Full Bundle (Recommended)
+### Full bundle (recommended)
 
-Import everything - tokens, reset, base styles, components, and utilities:
+Import everything -- tokens, reset, base styles, components, and utilities:
 
 ```css
 @import '@teseor/css/dist/index.css';
 ```
 
-### Option 2: Standalone Component
+### Standalone component
 
-Components include SCSS fallbacks and work without tokens:
+Components include hardcoded fallbacks and work without the token layer:
 
 ```css
-/* Works standalone - uses hardcoded fallback values */
 @import '@teseor/css/dist/components/button.css';
 ```
 
-Note: Without tokens, theming via CSS custom properties won't work.
+Without the full bundle, theming via CSS custom properties won't apply.
 
 ## Theming
 
-### Global Tokens
+### Global tokens
 
 Override design tokens at the root level:
 
 ```css
 :root {
-  --color-primary: hotpink;
-  --radius-md: 0;
+  --ui-color-primary: oklch(55% 0.25 270);
+  --ui-radius-base: 4px;
+  --ui-font-sans: "Inter", system-ui, sans-serif;
+  --ui-shadow-strength: 8%;
 }
 ```
 
-### Component-Level Overrides
+### Component-level overrides
 
-Each component exposes `--component-*` custom properties:
+Each component exposes `--ui-<component>-*` custom properties:
 
 ```css
 :root {
-  /* Override all buttons */
-  --button-bg: navy;
-  --button-radius: 0;
+  --ui-button-bg: navy;
+  --ui-button-radius: 0;
 }
 
 .my-special-button {
-  /* Override specific instance */
-  --button-bg: gold;
+  --ui-button-bg: gold;
 }
 ```
 
-## CSS Custom Property Cascade
+### Token cascade
 
-Components use a three-level fallback system:
+Components use a three-level fallback:
 
 ```
---button-bg -> --color-primary -> hardcoded fallback
+--ui-button-bg  ->  --ui-color-primary  ->  oklch(55% 0.22 250)
+ (component)         (global token)          (hardcoded fallback)
 ```
 
-1. **Component override** (`--button-bg`) - highest priority
-2. **Global token** (`--color-primary`) - design system default
-3. **SCSS fallback** (`hsl(220 85% 50%)`) - works standalone
+1. **Component token** (`--ui-button-bg`) -- highest priority, scoped override
+2. **Global token** (`--ui-color-primary`) -- design system default
+3. **Hardcoded fallback** -- static value for standalone usage
+
+## Components (62)
+
+| Category | Components |
+|----------|-----------|
+| **Actions** | button, button-group, close-button |
+| **Typography** | heading, link, code, code-block, kbd, blockquote, list, mark |
+| **Forms** | input, select, checkbox, radio, toggle, slider, textarea, fieldset, field, label, form, form-error, form-helper, number-input, password-input, search-input, checkbox-group, radio-group |
+| **Data display** | avatar, badge, card, table, tag, stat, status, data-list, icon, image |
+| **Feedback** | alert, spinner, progress, progress-circle, skeleton, toast |
+| **Overlays** | modal, dialog, drawer, tooltip, popover, overlay |
+| **Disclosure** | accordion, disclosure |
+| **Navigation** | tabs, breadcrumb, menu, dropdown-menu, nav, pagination |
+| **Content** | divider, spacer, scroll-area |
 
-## Available Components
+**Layout primitives** (16): app-shell, grid, column, row, box, center, container, content, sidebar, sidebar-nav, topbar, nav-rail, page-header, footer, main, aspect-ratio
 
-- `button` - Buttons with size and style variants
+**Utilities** (10): spacing, display, position, text, border, container, visually-hidden, scroll-snap, scroll-animation, view-transition
 
-## Folder Structure
+## Naming
+
+- **Classes (BEM)**: `.ui-button`, `.ui-button--primary`, `.ui-button__icon`
+- **Global tokens**: `--ui-color-primary`, `--ui-space-2`, `--ui-row-2`
+- **Component tokens**: `--ui-button-height`, `--ui-input-radius`
+- **Internal vars**: `--_bg`, `--_height` (component-scoped, not public API)
+
+## Source structure
 
 ```
 packages/css/src/
-  00-config/       # Layer definitions + global tokens
-  01-reset/        # Reset/normalize styles
-  02-base/         # Base HTML element styles
-  03-layout/       # Layout primitives (stack, grid, container)
-  04-components/   # UI components
-  05-utilities/    # Helper classes
-  99-debug/        # Dev tools
+  config/          # Layer order, design tokens, guides
+  reset/           # CSS reset
+  base/            # Base HTML element styles
+  layout/          # Layout primitives (grid, column, row, box, ...)
+  components/      # UI components grouped by category
+    actions/       # button, button-group, close-button
+    typography/    # heading, link, code, ...
+    forms/         # input, select, checkbox, ...
+    data-display/  # avatar, badge, card, ...
+    feedback/      # alert, spinner, progress, ...
+    overlays/      # modal, dialog, drawer, ...
+    disclosure/    # accordion, disclosure
+    navigation/    # tabs, breadcrumb, menu, ...
+    content/       # divider, spacer, scroll-area
+  utilities/       # Helper classes
+  debug/           # Dev tools (grid overlay, token inspector)
 ```
 
+Each component directory contains:
+- `index.scss` -- styles with internal tokens (`--_` prefix)
+- `<name>.api.json` -- CSS API definition (classes, modifiers, custom properties)
+- `<name>.docs.json` -- documentation content
+- `<name>.visual.spec.ts` -- visual regression test
+
 ## Development
 
 ```bash
-# Build
-pnpm nx run css:build
+pnpm nx build css          # build the package
+pnpm nx test css           # visual regression tests (Playwright)
+```
 
-# Watch
-pnpm nx run css:watch
+See the root [CONTRIBUTING.md](../../CONTRIBUTING.md) for the full development workflow.
 
-# Visual regression tests
-npx playwright test
-```
+## License
+
+[MIT](../../LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teseor/css",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "description": "CSS library - reset, primitives, components, utilities",
   "license": "MIT",
   "author": "letanure",