ui-foundations 0.1.0

package/docs/foundations/foundation-007-typography-selectors-and-specificity.md

@@ -0,0 +1,24 @@
+# Foundation-007: Typography Selectors and Specificity
+
+## Purpose
+
+Provide a consistent typography API with low selector specificity and predictable overrides.
+
+## Rules
+
+1. Heading elements (`h1`..`h6`) define baseline heading styles.
+
+2. `.heading` mirrors heading baseline styles for non-heading elements.
+
+3. Size/scale classes define typography variants:
+   - Heading sizes: `.heading-xxxl` to `.heading-sm`
+   - Text scale: `.text-xs` to `.text-xxxl`
+
+4. Use `:where()` for zero-specificity size/scale selectors where possible.
+
+5. Reserve data attributes (for example `[data-theme]`, `[data-density]`) for context/state, not as primary styling API.
+
+## Implications
+
+- Component styles can override typography defaults without `!important`.
+- API remains clear between semantic element defaults and class-based variants.

package/docs/foundations/foundation-008-mode-activation-and-consumer-control.md

@@ -0,0 +1,27 @@
+# Foundation-008: Mode Activation and Consumer Control
+
+## Purpose
+
+Support dark mode in a reusable way without forcing activation behavior on consumers.
+
+## Rules
+
+1. Token outputs are scope-ready, not runtime activation logic:
+   - Light tokens at `:root`
+   - Dark tokens at `:root[data-mode="dark"]`
+   - Brand tokens scoped by `data-brand`
+
+2. Core theme layer remains neutral:
+   - `src/core/themes/mode.css` keeps non-invasive base behavior (`color-scheme`)
+   - no hard-coded dark token overrides in core theme CSS
+
+3. Each consumer owns mode policy:
+   - whether dark mode is available
+   - how system preference is interpreted
+   - when/how `data-mode` is set/removed
+
+## Implications
+
+- No unintended global dark overrides in downstream consumers.
+- Clear separation between token definitions and runtime mode policy.
+- Consumers can implement light-only, manual toggle, or system-following behavior.

package/docs/foundations/foundation-009-component-boundaries-and-utility.md

@@ -0,0 +1,30 @@
+# Foundation-009: Component Boundaries and Utility Test
+
+## Purpose
+
+Ensure new UI building blocks are introduced only when they provide reusable system value, not one-off complexity.
+
+## Rules
+
+1. Run a boundary decision before creating any new component.
+   - First ask: can this be modeled as composition of an existing component family?
+   - Typical composition cases: grouping, layout wrappers, orchestration of existing parts.
+
+2. Promote to a standalone component only if at least one applies:
+   - distinct semantics/responsibility
+   - stable public API that is not just a thin wrapper
+   - independent lifecycle/behavior that needs dedicated ownership
+
+3. Apply the utility test ("Snowflake check"):
+   - If it solves only one local case, keep it local and avoid adding system-level surface.
+   - If it is reusable across products/contexts, model it at system level.
+
+4. Token work is independent from component boundaries.
+   - New tokens may be required in both paths.
+   - New tokens alone do not justify a new standalone component.
+
+## Implications
+
+- The system surface stays smaller and easier to maintain.
+- Documentation remains clearer by keeping compositions near their base component.
+- Reusable patterns still scale when they pass the utility test.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "ui-foundations",
+  "version": "0.1.0",
+  "description": "Token-first UI foundations with CSS, tokens, and React exports.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@ssh.source.tui:Thomas.Bielich/ui-foundations.git"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "docs/foundations/**"
+  ],
+  "exports": {
+    "./core.css": "./dist/core/index.css",
+    "./ui.css": "./dist/ui/index.css",
+    "./react": "./dist/react/index.js",
+    "./react/button": "./dist/react/button.js",
+    "./react/icon": "./dist/react/icon.js",
+    "./react/input": "./dist/react/input.js",
+    "./react/label": "./dist/react/label.js",
+    "./assets/*": "./dist/assets/*",
+    "./tokens/core.css": "./dist/tokens/css/core.tokens.css",
+    "./tokens/color.css": "./dist/tokens/css/color.light.tokens.css",
+    "./tokens/color-light.css": "./dist/tokens/css/color.light.tokens.css",
+    "./tokens/color-dark.css": "./dist/tokens/css/color.dark.tokens.css",
+    "./tokens/semantic.css": "./dist/tokens/css/semantic.tokens.css",
+    "./tokens/components.css": "./dist/tokens/css/component.tokens.css"
+  },
+  "scripts": {
+    "icons:generate-list": "node scripts/generate-icon-list.mjs",
+    "lint:js": "node scripts/lint-js.mjs",
+    "lint": "npm run lint:js",
+    "test:unit": "node --test tests/*.test.mjs",
+    "test": "npm run test:unit",
+    "smoke:check": "node scripts/smoke-check.mjs",
+    "tokens:generate": "node scripts/extract-tokens.js",
+    "tokens:validate": "node scripts/validate-tokens.mjs",
+    "tokens:build": "npm run tokens:generate",
+    "build:css": "node scripts/build-css.mjs",
+    "build:all": "npm run icons:generate-list && npm run tokens:generate && npm run build:css",
+    "build": "npm run build:all",
+    "pack:check": "npm pack --dry-run",
+    "release:check": "npm run ci:check && npm run pack:check",
+    "docs:build": "eleventy",
+    "docs:site": "npm run build:all && npm run docs:build",
+    "ci:check": "npm run lint && npm run test:unit && npm run build:all && npm run smoke:check && npm run tokens:validate && npm run docs:build",
+    "docs:dev": "npm run build:all && eleventy --serve"
+  },
+  "devDependencies": {
+    "@11ty/eleventy": "^3.1.2",
+    "@figma/code-connect": "^1.2.0",
+    "fast-glob": "^3.3.3",
+    "js-yaml": "^4.1.0",
+    "jsonc-parser": "^3.3.1",
+    "prismjs": "^1.30.0"
+  }
+}