@daydreamui/tokens 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,182 @@
-# Temporary Holding Version
+# Tokens
 
-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 local Daydream plugin for exploring, extracting, and applying a visual theme.
+Enable **Tokens** in Daydream's Plugins page (⌥⌘P). No account or external service is used.
+
+From this repository, install the plugin with:
+
+```sh
+pnpm install
+pnpm ship plugins/daydream.tokens --enable
+```
+
+The build produces `plugins/daydream.tokens/dist/index.js`. The install command
+copies the plugin into the user’s Daydream plugins folder and records its trust.
+
+1. Choose one of ten brand-inspired presets. The carousel shows three at a time.
+   Or select viewports and choose **Extract from selection**; selecting an element
+   extracts its containing page. Or select a frame in Figma desktop and choose
+   **From Figma**, shown while Figma's Dev Mode MCP server answers.
+2. Use **Refine tokens** to edit values. **Reset edits** restores the starting point.
+   Both operations affect only the preview.
+3. **Apply to selected viewports** writes the theme and adopts existing styles on
+   all selected pages. One Undo restores the entire action. Repeated viewports and
+   shared stylesheets are written once.
+4. **Create specimen page** creates a responsive HTML page for exploring the theme.
+
+The preview is a temporary working draft, retained while the panel is minimized
+and reset on reload or project change. The applied theme is ordinary CSS in the
+project's files. Undo changes the pages; it does not replace the working draft.
+
+## Applying a theme
+
+Apply first reads each selected page's rendered styles and plans its source edits,
+then writes through the public plugin API in one transaction. A refused write
+cancels the transaction. It maps matching global color variables to semantic roles and converts supported
+literal declarations to references to the new theme. Generated variables use a
+`--tokens-` prefix, keeping the project’s existing token names and formats intact.
+Component and conditional variable definitions remain authored. Inline styles are
+edited through the same API.
+
+Mapped styles include page, surface, action, text and border colors, font families,
+heading weight/tracking (including the weight in a heading’s `font` shorthand),
+corner radii, padding and gaps. Font conversion follows
+the observed body and heading families, preserving other families such as code and
+icon fonts. Spacing and radius values
+in px/rem retain their proportions to the observed base value; zero values stay
+zero. CSSOM parses individual values and supported shorthands. The plugin retains
+selectors, media queries, `!important`, comments, content and layout dimensions.
+
+A dedicated `:root:where(html)` rule holds the theme. Definitions are written into
+every stylesheet whose declarations adopt references, so unselected consumers of
+shared CSS receive the definitions too. Low-specificity heading, action and input
+rules cover otherwise unstyled elements in an unconditional editable stylesheet.
+Pages with authored cascade layers receive token values and source conversions,
+but no generic element defaults: an unlayered fallback would override those
+layers. Reapplying clears earlier generated defaults on these pages. Shared sheets
+also omit defaults when another page on the canvas uses layers. This conservative
+behavior stays within the existing plugin API; a page’s unstyled elements keep
+their browser defaults when layers are present.
+A page with only media-restricted sheets refuses Apply before any writes and asks
+for an unconditional stylesheet. Applying again updates these rules; a sparse
+extracted theme preserves omitted tokens and defaults still used by earlier edits. A page with no stylesheet gains its normal Daydream stylesheet/link;
+Undo removes that creation. Shared stylesheets affect every page that links them,
+including unselected pages.
+
+Role inference is heuristic. Unmatched colors, gradients, background images,
+shadows, SVG paints, complex calculations and unsupported units stay as authored.
+Existing variable usages stay intact; editable definitions may be updated or mapped.
+Interleaved comments inside a value are preserved by leaving that value unchanged.
+A necessary edit to a read-only or unsupported rule refuses the action before any
+writes. Conflicting mappings of a shared rule cancel the whole transaction. Adoption is
+bounded to 2,000 elements per page and operates on page viewports, including independent variants.
+
+## Extracting a theme
+
+Extraction uses computed styles from mounted pages. It proposes colors, typography,
+borders, radii, padding/gaps and shadows. Hidden subtrees are excluded. Duplicate
+viewports do not inflate observations; responsive differences remain alternatives.
+Results are bounded to 2,000 elements per viewport and five values per category.
+
+Values include browser defaults and are resolved at the selected widths. Extraction
+does not recover aliases, original units, hover states, pseudo-elements, iframe
+content or fonts/assets, and does not write to the project. Missing preview roles
+use specimen fallbacks.
+
+## From Figma
+
+**From Figma** reads the variables of what is selected in Figma desktop and loads
+them into the preview, named after the selected frame as Figma's listing of the
+selection names it (else "From Figma"). With several frames selected — up to 12;
+past that the error line names the cap — the variables of each are read by id,
+all at once under one bound of 40 s, and merged by name — the first frame's
+value of a name wins — under the origin "3 frames from Figma"; a frame Figma
+refuses, or that has not answered by the bound, is left out and counted among
+the tokens left out, and only every one left out is an error. A layer inside a
+component instance, which Figma lists with an id of its own shape and refuses
+to read by it, is left out before anything is asked and counted too; with
+nothing else selected the error line says to select its frame. Nothing
+selected, Figma not there, and Figma too slow to answer are each one sentence.
+It needs Figma desktop open with the Dev Mode MCP server enabled in its
+preferences (the server runs on this machine at `http://127.0.0.1:3845`), and a
+selected frame. The button is
+there only while that server answers: the panel asks when it opens, when a
+project opens and when this window gets focus back, so switching to Figma to
+select and returning is enough. Nothing is sent anywhere, and nothing is written
+to the project until Apply. The plugin's host part holds the connection
+(`bridge.ts`, through `@daydream/figma-devmode`); without a Daydream host, or
+with the host part off, the button is simply absent.
+
+A variable's path becomes one custom property: lowercase, every run of
+characters outside `a-z0-9` one dash (`color/brand/500` → `--color-brand-500`,
+`Spacing/MD` → `--spacing-md`), a collision numbered `-2`, `-3`. Colors and
+values with a unit stay as written. A bare number becomes `px`, unless the name
+says it is unitless (`opacity`, `weight`, `line-height`, `ratio`, `z`); with
+its `px` it is a length, so a weight never takes it. A family name or a stack
+under a font-like name (`font`, `family`, `type`) is kept as written (`Arial`,
+`Inter, sans-serif`); any other string is quoted. A value written as a reference
+to another variable (`{color/brand/500}`; a `$` is a literal) becomes
+`var(--color-brand-500)` when that variable is in the set — Figma's own server
+answers an alias resolved to its value, so this serves a pasted or hand-written
+text; a live import holds values alone, and a string whose text happens to be
+another variable's name is that text, quoted. Booleans, nested objects,
+references to variables outside the set, references that loop (two variables
+aliasing each other, one aliasing itself) and values the browser cannot parse
+are left out and counted in the status line.
+
+The shared roles are suggested from the end of each path, each role once, as a
+reference to the raw token (`--primary: var(--color-brand-500)`), so Apply
+writes `--tokens-primary: var(--tokens-color-brand-500)`: `background` from
+names ending in `background`, `bg`, `canvas`, `page` or `surface-0`; `foreground`
+from `foreground`, `fg`, `text`, `text-primary`, `text-default`, `on-background`
+or `ink`; `card` from `card`, `surface`, `elevated` or `panel`; `muted` from
+`muted`, `subtle` or `secondary-surface`; `muted-foreground` from
+`muted-foreground`, `text-secondary`, `secondary`, `hint` or `placeholder`;
+`primary` from `primary`, `brand`, `accent`, `action` or `cta`;
+`primary-foreground` from `primary-foreground`, `on-primary`, `on-brand` or
+`on-accent`; `border` from `border`, `stroke`, `outline` or `divider`; `radius`
+from `radius`, `corner` or `rounded`; `spacing` from `spacing`, `space`, `gap` or
+`unit`; `font-sans` from `font-sans`, `font-family`, `sans`, `body-font` or
+`font-body`; `font-heading` from `font-heading`, `heading-font` or `display`;
+`heading-weight` from `heading-weight` or `weight-bold`; `heading-tracking` from
+`heading-tracking`, `tracking` or `letter-spacing`. A trailing scale step
+(`500`, `md`, `default`) is set aside, and `500`, `default`, `base`, `main` or
+`md` is preferred when a scale has several steps; a variable named exactly as a
+role is that role when its value is of the role's kind, and is renamed with a
+number (`--primary-2`) when it is not, so a length never stands as a colour.
+A role no name answers is left out, as a sparse extraction is. The role tokens come first in Refine, then the raw tokens they reference,
+then the rest in Figma's order, up to the 100 tokens a theme may hold. An alias
+is kept with what it points at, link by link, or left out whole, so nothing a
+theme holds points at nothing; what the cap leaves out is counted too.
+
+## Presets
+
+Presets are original interpretations, not official brand themes or extracted design
+systems. They use system fonts and contain no brand assets. Their references are
+[Apple](https://www.apple.com/), [BMW](https://www.bmw.com/),
+[Spotify](https://open.spotify.com/), [Airbnb](https://www.airbnb.com/),
+[Nike](https://www.nike.com/), [Stripe](https://stripe.com/),
+[Linear](https://linear.app/), [Notion](https://www.notion.com/),
+[IKEA](https://www.ikea.com/), and [Ferrari](https://www.ferrari.com/).
+This is an independent implementation with no Graphical API or archive integration.
+
+The shared vocabulary is `--background`, `--foreground`, `--card`, `--muted`,
+`--muted-foreground`, `--primary`, `--primary-foreground`, `--border`, `--radius`,
+`--font-sans`, `--spacing`, `--font-heading`, `--heading-weight`, and
+`--heading-tracking`. These are preview names; Apply writes `--tokens-background`,
+`--tokens-primary`, etc. References between supplied tokens follow those names.
+Extracted alternatives are retained as additional tokens.
+
+## Validation
+
+`pnpm test:kernel <daydream-checkout> plugins/daydream.tokens` covers real canvas
+rendering, extraction, carousel navigation, source adoption, shared files, inline
+styles, responsive rules, repeated application, refusal rollback, undo and specimen
+creation, and the From Figma gesture with the host part's answers supplied in
+memory. The conversion and the host part are unit tests over hand-written
+variables and an injected client: no test contacts Figma. The plugin requires a
+Daydream build reporting API 3.0; see the repository’s kernel pin and release gate
+before shipping. Its runtime dependency is the workspace package
+`@daydream/figma-devmode`: its host entry is what the host part loads, and its
+browser entry (`@daydream/figma-devmode/browser`, the reachability probe) is
+what the panel bundles.