@0001-labs/design-system-1 0.0.0-stage → 0.3.0-alpha.13

package/README.md

@@ -1,3 +1,241 @@
-# Temporary Holding Version
+# Design system 1 (0.3.0-alpha.13)
 
-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 plug and play design system
+
+> A component-based design system built with Lit that provides reusable UI components with built-in theming, internationalization, and accessibility features.
+
+**Design system 1** is a comprehensive modern design system that provides a set of reusable UI components built with Web Components via Lit. Available via CDN or npm.
+
+## Installation
+
+```bash
+# Using Vite+ (recommended)
+vp add @0001-labs/design-system-1@alpha
+
+# Using npm
+npm install @0001-labs/design-system-1@alpha
+
+# Using yarn
+yarn add @0001-labs/design-system-1@alpha
+
+```
+
+**Note**: The package is being renamed from `ds-one` to `design-system-1`. The installation commands and CDN URLs below target the new name and will work after its first npm publication.
+
+## Quick Start
+
+### Classless CSS usage
+
+Load the separate semantic stylesheet and write ordinary HTML. Elements such as
+`button`, `input`, `section`, headings, tables, and code blocks are styled
+directly, so no component classes or JavaScript are required.
+
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@0001-labs/design-system-1@alpha/DS1/1-root/one.semantic.css"
+/>
+
+<section>
+  <h2>Welcome</h2>
+  <p>A native HTML interface styled by Design system 1.</p>
+  <label for="email">Email</label>
+  <input id="email" type="email" placeholder="you@example.com" />
+  <button type="button">Get started</button>
+</section>
+```
+
+The complete file is organized with comments for Root, Reset, Layout,
+Typography, Buttons, Forms, Sections, Tables, Code, Feedback, and Motion. It is
+an additional distribution: the existing `one.css` stylesheet and Lit Web
+Components remain unchanged.
+
+### Web Components via CDN
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <!-- CSS -->
+    <link
+      rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/@0001-labs/design-system-1@alpha/DS1/1-root/one.css"
+    />
+    <!-- Bundle -->
+    <script type="module">
+      import "https://cdn.jsdelivr.net/npm/@0001-labs/design-system-1@alpha/dist/design-system-1.bundle.min.js";
+    </script>
+  </head>
+  <body>
+    <ds-button variant="primary" text="Get Started"></ds-button>
+    <ds-text text="Welcome"></ds-text>
+  </body>
+</html>
+```
+
+### NPM Usage
+
+```tsx
+import "design-system-1/styles";
+import "design-system-1";
+```
+
+For the classless version, import only the semantic stylesheet:
+
+```ts
+import "design-system-1/DS1/1-root/one.semantic.css";
+```
+
+## Source snapshots in products
+
+Products can select shared Lit components without loading the full system's
+page, device or theme setup. `sync.exports.mjs` says what a product may copy:
+`languages`, `components`, `email` and `icons`. 0001's products copy them with
+Sync 1, naming what they take in their `sync.json`:
+
+```json
+{ "sources": { "Design system 1": { "components": { "to": "src/design", "components": ["button", "text", "row"] } } } }
+```
+
+Import the generated `components.ts` and `1-root/component-tokens.css` in the
+consumer. The copy carries the relative dependency graph
+(`scripts/component-graph.mjs`), including shared languages and SVG maps, and a
+`components-manifest.json` for the adoption report. Sync 1 records every file's
+hash in the product's `sync.lock.json`, and `sync1 check` fails on missing
+files or local drift. Files the copy did not write stay owned by the consumer.
+All component edits happen here, then consumers sync.
+
+Components use scoped `--ds-*` tokens so an embedded document can keep its own
+scale and theme. A product may configure those tokens at its surface.
+`ds-button control="host"` makes the custom element the accessible control
+for React event handlers and roles; the default keeps a native shadow button.
+`ds-text literal` preserves renderer-owned light DOM children; the default
+looks up translation keys. `ds-panel` provides header and footer slots around
+its body. The shared native-control sheet serves elements that need native
+form or third-party focus semantics.
+
+`ds-tooltip literal text="…"` accepts product-translated copy; omit `literal`
+for a shared translation key. It labels its slotted control, supports top and
+bottom placement, and dismisses on Escape. `ds-tabs` owns arrow, Home and End
+navigation for its tab controls; the product handles their clicks to select
+the corresponding content. Set `role="group"` for standalone filter choices.
+Host buttons accept `icon` and `trailing` slots for glyphs and counts.
+
+Reload the page after changing registered custom-element classes during
+development; the browser defines each element once per document.
+
+## Documentation
+
+See the full documentation for Design system 1 at: [**designsystem1.com**](https://designsystem1.com/)
+
+The Astro + Starlight site lives in `website/`. Run `vp run docs:dev` locally;
+see the [documentation contributor guide](website/README.md) for build and authoring instructions.
+
+The site uses Astro and Starlight. Run `vp run docs:dev` locally; see the
+[documentation authoring guide](website/README.md) and [issue list](docs/issue-list.md).
+
+## Design system 1 app
+
+The repository includes a React-based component workbench for refining semantic
+elements one at a time. The right panel always shows the complete
+`one.semantic.css` file and updates its root variables as spacing and theme
+controls change. Exports contain plain HTML and require no JavaScript runtime.
+
+```bash
+vp run app:dev
+```
+
+The app and documentation belong to this single project. The documentation lives
+at `/`, and the app lives at `/app/` on `designsystem1.com`. Both are built into
+`website/dist` and deployed together to the Cloudflare Worker named `designsystem1`.
+
+Build the complete website locally:
+
+```bash
+vp run site:build
+```
+
+Deploy the complete website from the repository root:
+
+```bash
+vp run deploy
+```
+
+The `app:deploy`, `docs:deploy`, and subproject `deploy` commands all use this same
+combined release. Cloudflare settings are defined in the root `wrangler.jsonc`.
+The same Worker serves published CSS at `/ds1/*` and authenticated publishing
+at `/api/artifacts/*`, using the existing R2 library bucket. Convex remains the
+backend for accounts and library metadata. All Cloudflare deployment commands
+release this single Worker. The legacy `dsone.dev/*` route also belongs to this
+Worker: documentation redirects to the new domain, while existing `/ds1/*`
+stylesheet URLs remain served directly. The public workbench is available at
+`/app/` and `/app/playground`.
+
+The existing Convex deployment is still `aromatic-lapwing-453` (development).
+Its publishing URLs point to `designsystem1.com`; development login-link capture
+is disabled. Account sign-in requires an email provider before it can be used
+on the public site. The workbench does not require an account.
+
+## Features
+
+### Internationalization
+
+- **Language keys**: Add a `translations.json` to your project and everything is translatable with the cycle type language button
+- **Multi-language**: Automatically switches language based on browser language settings
+
+### Core Components
+
+- **Web Components**: Built with Lit for maximum compatibility
+- **Responsive design**: Mobile-first approach with scaling factor
+- **Theme system**: CSS custom properties for easy customization
+
+### Completed Features
+
+- ✅ Core component library (ds-button, ds-text, ds-icon, etc.)
+- ✅ Theming system with accent colors
+- ✅ Internationalization with language keys
+- ✅ Responsive design with mobile scaling
+- ✅ CDN delivery via jsDelivr
+- ✅ NPM package published
+
+### In Progress
+
+- 🚧 Starlight documentation coverage and manual review ([issue list](docs/issue-list.md))
+- 🚧 Additional component variants and states defined in Figma
+
+## Architecture
+
+```
+Design system 1/
+├── dist/             # Built files for NPM
+├── DS1/
+│   ├── 0-face/       # Utilities for device detection, internationalization,
+│   │                 # localStorage preferences, pricing and theme
+│   ├── 1-root/       # Core styles, fonts, and design tokens
+│   │                 # (everything as CSS variables)
+│   ├── 2-core/       # Core components (banner, buttons, text, cycle,
+│   │                 # date, icon, input, tooltip)
+│   ├── 3-unit/       # Composite components (list, row, table)
+│   ├── 4-page/       # Page-level components for layout (layout, grid)
+│   └── x-icon/       # SVG icon library
+├── app/              # React workbench and account/library screens at /app/
+├── website/          # Documentation at /; combined site output in website/dist
+├── convex/           # Backend, authentication, libraries, and publishing actions
+├── services/         # Asset-serving and publishing routes
+├── packages/         # Shared CSS validation package
+├── e2e/              # End-to-end checks
+├── tests/            # Project checks
+└── wrangler.jsonc    # Shared website deployment configuration
+
+```
+
+## License
+
+MIT © [Design system 1](https://github.com/0001-labs/Design-system-1)
+
+## 🔗 Links
+
+- [**Website**](https://designsystem1.com/) - Official website
+- [**GitHub**](https://github.com/0001-labs/Design-system-1) - Source code and issues
+- [**NPM Package**](https://www.npmjs.com/package/design-system-1) - Install with `@alpha` tag
+- [**CDN**](https://cdn.jsdelivr.net/npm/@0001-labs/design-system-1@alpha/) - Direct browser usage

package/dist/0-face/control.d.ts

@@ -0,0 +1,24 @@
+import { LitElement, type PropertyDeclarations } from "lit";
+/**
+ * The element is the control.
+ *
+ * A host control carries the role,
+ * takes focus, answers Enter and Space, and reports itself disabled. React's
+ * handlers, the accessibility tree and Testing Library then all meet one node
+ * in the light DOM, and there is no second interactive element nested inside
+ * the first.
+ *
+ * The role defaults to `button`; an element that is a tab, an option or a menu
+ * item says so with its own `role` attribute, which is left as written.
+ */
+export declare abstract class Control extends LitElement {
+    #private;
+    static properties: PropertyDeclarations;
+    protected get hostControl(): boolean;
+    protected syncControl(): void;
+    get disabled(): boolean;
+    set disabled(value: boolean);
+    constructor();
+    connectedCallback(): void;
+}
+//# sourceMappingURL=control.d.ts.map

package/dist/0-face/control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../../DS1/0-face/control.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,oBAAoB,EAAE,MAAM,KAAK,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,8BAAsB,OAAQ,SAAQ,UAAU;;IAC5C,MAAM,CAAC,UAAU,EAAE,oBAAoB,CAKrC;IAIF,SAAS,KAAK,WAAW,IAAI,OAAO,CAAiB;IACrD,SAAS,CAAC,WAAW,IAAI,IAAI;IAE7B,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,QAAQ,CAAC,KAAK,EAAE,OAAO,EAO1B;;IAWD,iBAAiB,IAAI,IAAI;CAiD5B"}

package/dist/0-face/control.js

@@ -0,0 +1,117 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _Control_instances, _Control_disabled, _Control_enabledTabIndex, _Control_syncDisabled, _Control_onClick, _Control_onKeyDown, _Control_onKeyUp;
+import { LitElement } from "lit";
+/**
+ * The element is the control.
+ *
+ * A host control carries the role,
+ * takes focus, answers Enter and Space, and reports itself disabled. React's
+ * handlers, the accessibility tree and Testing Library then all meet one node
+ * in the light DOM, and there is no second interactive element nested inside
+ * the first.
+ *
+ * The role defaults to `button`; an element that is a tab, an option or a menu
+ * item says so with its own `role` attribute, which is left as written.
+ */
+export class Control extends LitElement {
+    get hostControl() { return true; }
+    syncControl() { if (this.isConnected)
+        __classPrivateFieldGet(this, _Control_instances, "m", _Control_syncDisabled).call(this); }
+    get disabled() {
+        return __classPrivateFieldGet(this, _Control_disabled, "f");
+    }
+    set disabled(value) {
+        const old = __classPrivateFieldGet(this, _Control_disabled, "f");
+        __classPrivateFieldSet(this, _Control_disabled, Boolean(value), "f");
+        // An element may not gain attributes before it is in a document; React
+        // sets properties first, and connectedCallback catches up.
+        if (this.isConnected)
+            __classPrivateFieldGet(this, _Control_instances, "m", _Control_syncDisabled).call(this);
+        this.requestUpdate("disabled", old);
+    }
+    constructor() {
+        super();
+        _Control_instances.add(this);
+        _Control_disabled.set(this, false);
+        _Control_enabledTabIndex.set(this, void 0);
+        _Control_onClick.set(this, (event) => {
+            if (!this.disabled)
+                return;
+            event.preventDefault();
+            event.stopImmediatePropagation();
+        });
+        _Control_onKeyDown.set(this, (event) => {
+            if (!this.hostControl || this.disabled || event.target !== this)
+                return;
+            if (event.key === "Enter") {
+                event.preventDefault();
+                this.click();
+            }
+            else if (event.key === " ") {
+                // Space clicks on release, as a native button does; stop the page from
+                // scrolling in the meantime.
+                event.preventDefault();
+            }
+        });
+        _Control_onKeyUp.set(this, (event) => {
+            if (!this.hostControl || this.disabled || event.target !== this)
+                return;
+            if (event.key === " ") {
+                event.preventDefault();
+                this.click();
+            }
+        });
+        this.addEventListener("keydown", __classPrivateFieldGet(this, _Control_onKeyDown, "f"));
+        this.addEventListener("keyup", __classPrivateFieldGet(this, _Control_onKeyUp, "f"));
+        // Registered on the element itself so it runs before the click reaches
+        // React's root listener.
+        this.addEventListener("click", __classPrivateFieldGet(this, _Control_onClick, "f"), { capture: true });
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        if (this.hostControl && !this.hasAttribute("role"))
+            this.setAttribute("role", "button");
+        __classPrivateFieldGet(this, _Control_instances, "m", _Control_syncDisabled).call(this);
+    }
+}
+_Control_disabled = new WeakMap(), _Control_enabledTabIndex = new WeakMap(), _Control_onClick = new WeakMap(), _Control_onKeyDown = new WeakMap(), _Control_onKeyUp = new WeakMap(), _Control_instances = new WeakSet(), _Control_syncDisabled = function _Control_syncDisabled() {
+    this.toggleAttribute("disabled", __classPrivateFieldGet(this, _Control_disabled, "f"));
+    if (!this.hostControl)
+        return;
+    if (!this.hasAttribute("role"))
+        this.setAttribute("role", "button");
+    if (__classPrivateFieldGet(this, _Control_disabled, "f")) {
+        if (__classPrivateFieldGet(this, _Control_enabledTabIndex, "f") === undefined)
+            __classPrivateFieldSet(this, _Control_enabledTabIndex, this.getAttribute("tabindex"), "f");
+        this.setAttribute("aria-disabled", "true");
+        this.setAttribute("tabindex", "-1");
+    }
+    else {
+        this.removeAttribute("aria-disabled");
+        if (__classPrivateFieldGet(this, _Control_enabledTabIndex, "f") !== undefined) {
+            if (__classPrivateFieldGet(this, _Control_enabledTabIndex, "f") === null)
+                this.setAttribute("tabindex", "0");
+            else
+                this.setAttribute("tabindex", __classPrivateFieldGet(this, _Control_enabledTabIndex, "f"));
+            __classPrivateFieldSet(this, _Control_enabledTabIndex, undefined, "f");
+        }
+        else if (!this.hasAttribute("tabindex"))
+            this.setAttribute("tabindex", "0");
+    }
+};
+Control.properties = {
+    // The accessor is our own: disabled changes what the element does and
+    // what assistive technology hears, so it reaches the DOM at once rather
+    // than on Lit's next update.
+    disabled: { type: Boolean, reflect: true, noAccessor: true },
+};

package/dist/0-face/define.d.ts

@@ -0,0 +1,3 @@
+/** Register a shared element once; a fresh page picks up changes during HMR. */
+export declare function define(name: string, element: CustomElementConstructor): void;
+//# sourceMappingURL=define.d.ts.map

package/dist/0-face/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../DS1/0-face/define.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAG5E"}

package/dist/0-face/define.js

@@ -0,0 +1,7 @@
+/** Register a shared element once; a fresh page picks up changes during HMR. */
+export function define(name, element) {
+    if (typeof customElements === "undefined")
+        return;
+    if (!customElements.get(name))
+        customElements.define(name, element);
+}

package/dist/0-face/device.d.ts

@@ -0,0 +1,71 @@
+import { type ScalingConfig } from "./scaling";
+export type { ScalingConfig, ScalingMode } from "./scaling";
+export type DeviceType = "mobile" | "tablet" | "desktop";
+export interface DeviceInfo {
+    isMobile: boolean;
+    isTablet: boolean;
+    isDesktop: boolean;
+    isTouchCapable: boolean;
+    deviceType: DeviceType;
+    userAgent: string;
+    screenWidth: number;
+    screenHeight: number;
+}
+/** Reactive scaling factor signal */
+export declare const scalingFactor: import("@lit-labs/signals").Signal.State<number>;
+/** Current scaling configuration */
+export declare const scalingConfig: import("@lit-labs/signals").Signal.State<ScalingConfig>;
+/**
+ * Comprehensive mobile device detection
+ * Combines user agent detection, touch capability, and viewport size
+ */
+export declare function detectMobileDevice(): boolean;
+/**
+ * Get detailed device information
+ */
+export declare function getDeviceInfo(): DeviceInfo;
+/**
+ * Calculate the scaling factor based on viewport width
+ * @param viewportWidth - Current viewport width in pixels
+ * @param config - Scaling configuration
+ * @returns The calculated scaling factor
+ */
+export declare function calculateScalingFactor(viewportWidth: number, config?: ScalingConfig): number;
+/**
+ * Set the scaling configuration
+ * @param config - Partial scaling configuration to apply
+ */
+export declare function setScalingConfig(config: Partial<ScalingConfig>): void;
+/**
+ * Update the scaling factor based on current viewport
+ * Desktop always uses factor 1; mobile uses computed factor
+ */
+export declare function updateScalingFactor(): void;
+/**
+ * Get the current scaling factor
+ * @returns The current scaling factor
+ */
+export declare function getScalingFactor(): number;
+/**
+ * Convert a design pixel value to scaled pixels
+ * @param designPx - The design pixel value (based on 280px width)
+ * @returns The scaled pixel value
+ */
+export declare function scale(designPx: number): number;
+/**
+ * Convert a scaled pixel value back to design pixels
+ * @param scaledPx - The scaled pixel value
+ * @returns The design pixel value
+ */
+export declare function unscale(scaledPx: number): number;
+/**
+ * Initialize device detection and scaling
+ * Sets CSS classes (.mobile/.desktop) and --sf custom property
+ */
+export declare function initDeviceDetection(): DeviceInfo;
+/**
+ * Disable double-tap to zoom in the browser (app-like behavior)
+ * Prevents all zoom gestures including double-tap and pinch-to-zoom
+ */
+export declare function applike(): void;
+//# sourceMappingURL=device.d.ts.map

package/dist/0-face/device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../../DS1/0-face/device.ts"],"names":[],"mappings":"AAIA,OAAO,EAAkE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/G,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAM5D,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,OAAO,CAAC;IACxB,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qCAAqC;AACrC,eAAO,MAAM,aAAa,kDAAoB,CAAC;AAE/C,oCAAoC;AACpC,eAAO,MAAM,aAAa,yDAA8C,CAAC;AAMzE;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CA0B5C;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,CA6B1C;AAMD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,EACrB,MAAM,GAAE,aAAmC,GAC1C,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI,CASrE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAiC1C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGhD;AAMD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,UAAU,CA8ChD;AAiCD;;;GAGG;AACH,wBAAgB,OAAO,IAAI,IAAI,CA4H9B"}