@sylwellsoftware/fray 1.1.0 → 1.1.1

package/colors/README.md

@@ -1,27 +1,38 @@
 # Fray color palettes
 
-Each `<name>/colors.css` file is a replaceable variable-only palette. It does
-not decide what a panel, button, input, selection, or application surface looks
-like, and it never imports another stylesheet.
+Each `<name>/colors.css` file is a replaceable, variable-only palette. It owns
+color anchors and endpoints, not the appearance of a panel, button, input,
+selection, or application surface. Palette files contain no component
+selectors and never import another stylesheet.
 
-A palette normally supplies:
+Published palettes are `gray`, `green`, `iceblue`, `ocean`, `orange`, `purple`,
+`red`, and `yellow`.
+
+## Palette contract
+
+A palette supplies:
 
 - `--palette-light` and `--palette-dark` endpoints;
-- light/dark contrast colors and named red/green primitives;
+- `--palette-contrast-light` and `--palette-contrast-dark` foregrounds;
+- `--palette-red` and `--palette-green` status primitives;
 - `--palette-primary-500`, `--palette-secondary-500`, and
   `--palette-neutral-500` anchors.
 
-`themes/base.css` derives the remaining numeric ramp stops and the ordinary
-`primary`, `light`, and `dark` aliases with `color-mix`. It also derives clear
-and faint translucent variants of the light endpoint for palette-aware chrome.
-A palette may override `--palette-<family>-light-mix` or
-`--palette-<family>-dark-mix` when a ramp intentionally changes hue.
+`themes/base.css` derives the remaining numeric ramp stops, ordinary
+`primary`/`light`/`dark` aliases, and transparent light variants with
+`color-mix()`. A palette may override a
+`--palette-<family>-light-mix` or `--palette-<family>-dark-mix` endpoint when a
+ramp intentionally changes hue.
 
 ```css
 @layer palette {
   :root {
     --palette-light: #fff;
     --palette-dark: #111827;
+    --palette-contrast-light: #fff;
+    --palette-contrast-dark: #111827;
+    --palette-red: #c62828;
+    --palette-green: #2e7d32;
     --palette-primary-500: #2989d8;
     --palette-secondary-500: #7137a8;
     --palette-neutral-500: #7892aa;
@@ -29,6 +40,24 @@ A palette may override `--palette-<family>-light-mix` or
 }
 ```
 
-Color files contain no semantic `--button-*`, `--input-*`, or `--panel-*`
-variables and no descendant selectors. Themes map the derived palette to those
-semantic roles.
+Color files must not declare semantic roles such as `--button-*`,
+`--input-*`, or `--panel-*`. The base and active theme map derived palette
+values to those roles.
+
+## Loading and replacement
+
+Load one palette after Fray's base and structural CSS and before the active
+theme:
+
+```ts
+import '@sylwellsoftware/fray/colors/iceblue/colors.css'
+```
+
+`frayColorOptions` lists the built-in files. `ColorPicker` and
+`replaceFrayStylesheet('colors', option)` replace the link marked
+`data-fray-stylesheet="colors"`; applications own selection and persistence
+policy.
+
+When adding a palette, test its derived ramps and contrast in every supported
+theme, forced-colors mode, and application states that introduce semantic
+status colors.

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@sylwellsoftware/fray",
   "private": false,
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Browser-only TypeScript component runtime, JSX controls, and semantic themes.",
   "license": "Apache-2.0",
   "author": {
@@ -63,11 +63,11 @@
     "./themes/**/*.css"
   ],
   "peerDependencies": {
-    "@sylwellsoftware/glue": "^0.8.0"
+    "@sylwellsoftware/glue": "^0.8.1"
   },
   "devDependencies": {
     "vite": "^6.3.5",
-    "@sylwellsoftware/glue": "^0.8.0"
+    "@sylwellsoftware/glue": "^0.8.1"
   },
   "engines": {
     "node": ">=22",

package/themes/README.md

@@ -1,33 +1,41 @@
-# Fray base and theme CSS
+# Fray base and themes
 
-Fray presentation is loaded in this order:
+Fray presentation is assembled from independently owned files in this order:
 
-1. `themes/base.css`: custom-property defaults and palette derivation only.
-2. Runtime-collected structural CSS for the application's declared components.
-3. One `colors/<name>/colors.css`: palette anchors and endpoints only.
-4. One `themes/<name>/theme.css`: intentional custom-property overrides only.
+1. `themes/base.css` — defaults and palette derivation.
+2. Collected component CSS or `styles/structural.css` — selectors and layout.
+3. One `colors/<name>/colors.css` — palette anchors and endpoints.
+4. One `themes/<name>/theme.css` — intentional semantic-role overrides.
 
-Application-owned layout CSS is separate from these Fray inputs.
+Application layout CSS is separate from these inputs.
 
 ## Base file
 
-`base.css` provides usable default palette anchors, derives the primary,
-secondary, and neutral ramps, and declares semantic defaults. It contains no
-component selectors and no declarations that consume those variables.
+`base.css` provides usable default palette anchors, derives primary, secondary,
+and neutral ramps, and declares the semantic variable fallback hierarchy. It
+contains no component selectors and no declarations that consume those
+variables.
 
-The application imports it explicitly. Named themes and colors never import it,
-which keeps ownership and load order visible.
+Applications import the base explicitly. Named themes and palettes never
+import it, so the cascade and ownership order remain visible.
 
 ## Theme files
 
-A theme changes only variables. The sole ordinary-property exception is
-`color-scheme`, because it informs browser-native rendering. A theme must not
-contain component, trait, part, ARIA-state, or pseudo-element selectors. Those
-selectors belong to component `static css` even when their values are driven by
-theme variables.
+Published themes are:
 
-Start with no overrides. Add a variable only when it produces a deliberate
-visual difference from `base.css`; do not repeat defaults for completeness.
+| Theme | Appearance capability | Intent |
+| --- | --- | --- |
+| `minimal` | Adaptive (`light`, `dark`, or system) | Restrained platform-oriented treatment |
+| `java` | Light | Desktop control treatment inspired by classic Java interfaces |
+| `shiny` | Light | Gloss, depth, and chromed graphical surfaces |
+
+A theme changes custom properties. The sole ordinary-property exception is
+`color-scheme`, which informs browser-native rendering. Themes must not contain
+component, trait, part, ARIA-state, or pseudo-element selectors; those belong
+to the component's `static css`.
+
+Start a new theme with no overrides and add a variable only when it creates an
+intentional difference from `base.css`:
 
 ```css
 @layer theme {
@@ -39,6 +47,22 @@ visual difference from `base.css`; do not repeat defaults for completeness.
 }
 ```
 
-`frayThemeVariableCatalog` publishes the supported palette and semantic
-variable contract. Component-specific variables should fall back through a
-shared family so a theme can remain small.
+`frayThemeVariableCatalog` is the machine-readable public contract. Its
+fallback chain runs from palette roles through global UI roles and shared
+families, then to optional component-specific roles. A small theme can
+therefore override a family without naming every component.
+
+## Runtime selection and appearance
+
+`frayThemeOptions` lists built-in theme links and their light/dark capability.
+`ThemePicker` or `replaceFrayStylesheet('theme', option)` replaces the marked
+theme link. `setFrayAppearance('light' | 'dark' | 'system')` controls adaptive
+themes; `system` removes the explicit root attribute so browser preference
+applies.
+
+Theme availability, default selection, persistence, and whether users can
+switch at runtime are application policy.
+
+When changing a theme, verify all supported palettes, native control states,
+keyboard focus, disabled/error/selection contrast, forced colors, reduced
+motion, and 200% text.