@rcarls/rc-theme-win31 0.0.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,185 @@
+# @rcarls/rc-theme-win31
+
+## 0.7.0
+
+### Minor Changes
+
+- 19278d4: Group several native controls into one `rc-field` with a direct `<fieldset>`. Its `<legend>` names
+  the group and shows as the field label, each control keeps its own accessible name, and supporting
+  text describes the fieldset. The first text-like input or textarea is the primary control behind
+  `control`, `focus()`, and `data-populated`; focus moving between grouped controls keeps the field
+  focused; and `data-disabled`, `data-required`, and `data-invalid` reflect the whole group. New
+  read-only `group` and `controls` properties and a `data-group` host attribute support the mode.
+
+  The primary control grows and other controls attach before or after it. In Material, the legend uses
+  the floating label mechanics: it rests on the input line while the group is idle and its primary
+  input empty, and floats on focus or once that input has a value; a group with a control before its
+  primary input keeps it floated. Grouped placeholders wait for focus. Substrate colors an invalid
+  group's legend, and Win31 spaces it like a single field's label.
+
+- 873592e: Add four directional motion tokens to the shared base contract:
+  `--rc-motion-effects-easing-enter`/`-exit` and
+  `--rc-motion-spatial-easing-enter`/`-exit`. An opening element decelerates
+  into place; a closing one accelerates out. There are no matching enter/exit
+  duration tokens; pair `-easing-exit` with an existing `-duration-fast` token
+  instead.
+
+  All three themes map the new tokens: Material pairs them with its
+  standard/emphasized decelerate and accelerate curves, Substrate keeps its one
+  curve as the enter curve and adds a generic accelerate shape for exit
+  (refined further once Substrate gets its own full spatial/effects scale), and
+  `rc-theme-win31` declares all four as `step-end`, matching its zero-motion
+  contract, so an application that loads the shared base tokens alongside
+  `rc-theme-win31` does not inherit the base defaults' real easing curves for
+  these two directions.
+
+- c62d107: Let opt-in native theme styles reach consumer controls inside RC containers while
+  component recipes retain their themed presentation. Apply the same presentation
+  boundary and `data-rc-native="off"` subtree opt-out in Material, Substrate, and
+  Windows 3.1.
+
+  Native controls inside an RC host may now gain theme styling when that host does
+  not provide their appearance. Add `data-rc-native="off"` to content that should
+  keep its own styles, such as a third-party widget.
+
+- 622c5c9: Add independent opt-in `native.css` and CSS-only `css-components.css` entrypoints to the
+  Material, Substrate, and Windows 3.1 themes. Native controls can use the theme presentation
+  without registration, while documented class recipes style common HTML controls and static
+  card, list, chip-group, and disclosure markup without changing behavior.
+
+  Native styles stop at RC controls that own their native children. Add
+  `data-rc-native="off"` to an element to keep native styles off it and its subtree.
+
+- 687a9be: Add shared popup surface tokens: `--rc-popup-background`, `--rc-popup-color`,
+  `--rc-popup-border`, `--rc-popup-radius`, `--rc-popup-shadow`, and
+  `--rc-popup-padding-block`. Menus, adaptive-menu popups, and select and
+  combobox listboxes read them before their own fallbacks. Themes set them at the
+  theme root, so popups rendered inside other shadow roots keep the theme's
+  surface. Select and combobox add `--rc-*-listbox-background` and
+  `--rc-*-listbox-color`.
+
+  Breaking: popup surfaces no longer fall back to `--rc-control-radius`. Set
+  `--rc-popup-radius` (or the per-component radius token) to change popup
+  corners. The Material, Substrate, and Win31 themes no longer set per-component
+  popup surface tokens such as `--rc-menu-radius` or
+  `--rc-adaptive-menu-popup-background`; override the `--rc-popup-*` tokens
+  instead. Material select and combobox listboxes now use the menu container
+  color, Material forced-colors popups gain a border, and Substrate listboxes use
+  the menu shadow and padding. Material retains its two-layer adaptive-menu popup
+  shadow through a component token while other popups continue using the shared
+  shadow.
+
+- 6d126fd: Add shared item type tokens: `--rc-item-font-family`, `--rc-item-font-size`,
+  `--rc-item-font-weight`, `--rc-item-line-height`, `--rc-item-letter-spacing`,
+  and `--rc-item-icon-size`. Menu, listbox, and adaptive-menu items read them.
+  Adaptive menu adds `--rc-adaptive-menu-trigger-hover-background`,
+  `--rc-adaptive-menu-trigger-shadow`, and
+  `--rc-adaptive-menu-trigger-active-shadow`, and styles overflowed `rc-button`
+  and `rc-menu-button` rows from its item tokens. Themes declare their menu,
+  adaptive-menu, and item tokens on the theme root, so menus inside other shadow
+  roots match menus in the document. Substrate's adaptive-menu trigger now shows
+  its hover background.
+
+  Breaking: theme menu and adaptive-menu tokens are inherited from the theme root
+  instead of set on each element, so a value set on an ancestor now reaches
+  nested menus. Material sets menu, listbox, and adaptive-menu item type through
+  `--rc-item-*` instead of per-component rules; override those tokens to change
+  item type. Themes no longer style the adaptive-menu trigger through
+  `::part(overflow-trigger)` hover and pressed rules; use the new trigger tokens.
+
+- fb747f6: Declare `rc-base` before each theme's own layers. Components inject their structural
+  light-DOM CSS into `rc-base` at runtime, after the theme has loaded, which made it the last
+  and strongest layer on pages that don't declare their own order, so it could override theme
+  rules. Theme rules now win either way. Apps that declare their own layer order should list
+  `rc-base` before the theme layers.
+
+  Add a fourth theme layer, `rc-theme-*.overrides`, after `.components`. Each theme uses it to
+  keep `rc-adaptive-menu` overflow rows on the menu's item tokens. Theme button and menu-button
+  variants, such as Material's icon-only sizing and filled colors or Win31's bevelled native
+  buttons, no longer restyle an overflowed action as a standalone control. A demoted
+  icon-only `rc-menu-button` keeps its row padding and indicator inset.
+
+- 58f4e71: `rc-theme-substrate` and `rc-theme-win31` now map the full shared
+  spatial/effects motion scale that `rc-theme-material` already implements,
+  closing a gap where each declared only its own single compatibility duration.
+
+  Substrate adds a small, quicker scale of its own: 100/160/240&nbsp;ms for
+  effects and 160/240/320&nbsp;ms for spatial, with its existing single easing
+  curve as the spatial curve (it is already decelerate-shaped) and `ease-out`
+  for effects. The compatibility token now follows the effects default rather
+  than its own literal, matching the shared base contract's own convention.
+  The one remaining hardcoded duration, `rc-list-item`'s 100&nbsp;ms row
+  transition, now reads from the effects-fast token. Substrate's
+  `prefers-reduced-motion` override moves from the bridge layer into
+  `components/modes.css`, in the components layer, matching where the other
+  two themes keep their mode overrides; a cascade layer test now proves the
+  later layer's override wins rather than assuming it.
+
+  win31 declares all thirteen shared tokens, plus the four directional ones
+  added last release, at zero duration with `step-end` easing. Previously only
+  the single compatibility token was set, so an application loading the shared
+  base tokens alongside this theme inherited base's real 180/300/450&nbsp;ms
+  spatial motion for every other token in the scale, silently contradicting the
+  theme's own zero-motion contract. `rc-chip`'s existing zero-duration override
+  gets its matching `step-end` easing token.
+
+  Verifying that claim surfaced a limit worth knowing about even after this
+  fix: it holds only when the theme class is applied to a container, the
+  documented pattern, not to `<html>`. The shared `base.css` declares no cascade
+  layer, so its `:root` values outrank any theme layer whenever both target the
+  same element, which happens only when the theme class sits on `<html>` itself.
+  No theme package can fix this by declaring more tokens; see the styling guide
+  for details.
+
+- 0deda8a: Theme `rc-popover` and `rc-tooltip`. Tooltips, which Windows 3.1 did not have,
+  borrow its WinHelp definition popup: a white box with a hard one-pixel frame and
+  drop shadow. Popovers keep the theme's menu panel with panel spacing. Both sets
+  of tokens sit on the theme root, so surfaces inside other shadow roots inherit
+  them.
+- 322d875: Add a Windows 3.1 era theme package with full component coverage.
+
+  `@rcarls/rc-theme-win31` maps a period `--win31-*` token layer onto the public
+  `--rc-*` contract and ships one stylesheet per component, matching the coverage
+  of the existing themes. Metrics derive from the MS Sans Serif 8pt cell and scale
+  from a single `--win31-unit` token, so the theme can be doubled without any
+  proportion changing.
+
+  The theme is light only, has no hover states outside menus, treats disabled as a
+  color rather than an opacity, draws focus and selection as separate marks, and
+  yields entirely under forced colors.
+
+### Patch Changes
+
+- fef89dc: Move the segmented appearance into the component behind one switch.
+
+  Turning the native fieldset into a segmented control took 27 `--_rc-*`
+  declarations that every theme had to restate, 23 of them byte-identical. Two of
+  those blocks were accessibility recipes rather than taste: the visually hidden
+  legend that keeps the group's accessible name, and the hidden but focusable
+  radio. A theme that got either wrong removed the accessible name or made the
+  control unreachable by keyboard.
+
+  The component now owns the recipe and a theme sets
+  `--rc-segmented-button-appearance: segmented`. Four genuine theme choices become
+  public properties: `--rc-segmented-button-cursor`,
+  `--rc-segmented-button-disabled-cursor`,
+  `--rc-segmented-button-vertical-divider`, and
+  `--rc-segmented-button-selected-icon-display`.
+
+  Unset, the fieldset, legend, and radios keep their browser appearance, as
+  before. The switch is read with a style container query (Chrome 111, Safari 18,
+  Firefox 128); where that is unsupported the recipe does not apply and the
+  control falls back to the same native appearance.
+
+  To migrate a theme, replace its `--_rc-segmented-button-*` block with the single
+  `--rc-segmented-button-appearance: segmented` declaration, plus any of the four
+  public properties whose value differs from the default.
+
+- edfd374: Icon slots keep their square while empty. An SVG icon element such as
+  `<iconify-icon>` draws a frame after it mounts, so swapping one in, such as a
+  filter chip's check, no longer collapses the slot and shifts the row for a
+  frame. Icon-font glyphs already fill 1em and render the same.
+- 50687d3: Publish a Windows 3.1 design guide with checked theme values and composition
+  guidance. Align the push-button minimum with the documented dialog-unit size,
+  let dithered surfaces follow palette overrides, and correct the default-button
+  example.

package/DESIGN.md

@@ -0,0 +1,195 @@
+---
+version: windows-3.1-ctl3d-inspired
+name: rc-theme-win31
+description: >
+  Composition guide for Windows 3.1-era applications built with
+  rc-webcomponents and the rc-theme-win31 CSS theme. Values describe the
+  package's shipped baseline; historical measurements are identified below.
+colors:
+  surface: '#c0c0c0'
+  highlight: '#ffffff'
+  shadow: '#808080'
+  shadow-dark: '#404040'
+  frame: '#000000'
+  field: '#ffffff'
+  field-text: '#000000'
+  menu: '#c0c0c0'
+  menu-text: '#000000'
+  selection: '#000080'
+  selection-text: '#ffffff'
+  title-active: '#000080'
+  title-active-text: '#ffffff'
+  title-inactive: '#808080'
+  title-inactive-text: '#c0c0c0'
+  desktop: '#008080'
+typography:
+  family: 'Microsoft Sans Serif, MS Sans Serif, Tahoma, Segoe UI, sans-serif'
+  body-size: 13px
+  menu-size: 16px
+  title-size: 16px
+geometry:
+  unit: 1px
+  control-height: 23px
+  title-height: 24px
+  menu-height: 27px
+  toolbar-height: 31px
+  toolbar-button-size: 27px
+  listbox-row-height: 17px
+  scrollbar-size: 16px
+  check-size: 13px
+  gap: 4px
+components:
+  button:
+    surface: '{colors.surface}'
+    text: '{colors.frame}'
+    minHeight: '{geometry.control-height}'
+  dialog:
+    surface: '{colors.surface}'
+    title: '{colors.title-active}'
+    captionHeight: '{geometry.title-height}'
+  listbox:
+    surface: '{colors.field}'
+    selection: '{colors.selection}'
+    rowHeight: '{geometry.listbox-row-height}'
+  scrollbar:
+    size: '{geometry.scrollbar-size}'
+---
+
+# rc-theme-win31 design guide
+
+This guide helps people and coding agents compose an application with
+`@rcarls/rc-theme-win31`. It describes the shipped Windows 3.1-era appearance,
+its component contracts, and the points where web rendering is an approximation.
+The [component documentation](https://richardcarls.github.io/rc-webcomponents/)
+remains the reference for individual attributes and events.
+
+## Historical target and evidence
+
+The theme uses square geometry, bitmap-like marks, hard shadows, and an optional
+beveled control treatment associated with applications using CTL3D. The 1992
+[_Windows Interface: An Application Design Guide_](https://books.google.com/books/about/The_Windows_Interface.html?id=ONBQAAAAYAAJ)
+is the period design reference. Microsoft's
+[dialog-unit conversion](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-mapdialogrect)
+explains why pixel dimensions depend on the dialog font. The measurements in
+this package are a 96 DPI, 8 pt MS Sans Serif approximation, not a claim that
+every Windows 3.1 application rendered at one pixel size.
+
+[Shell.css](https://zachhall.org/shell-css/) and
+[Web31](https://github.com/Futur3Sn0w/web31) are useful independent web
+recreations for visual comparison. Their assets, palette choices, and window
+manager behavior are not specifications for this component theme. The
+originator `stars` application uses its own sampled game palette, including a
+light-blue title; those values belong to an application override, not this
+package's baseline.
+
+## Compose an application
+
+Import the complete theme and place its scope on the application root. Put the
+scope on `<html>` when native dialogs or popovers may enter the top layer.
+
+```css
+@import '@rcarls/rc-theme-win31/theme.css';
+```
+
+```html
+<html class="rc-theme-win31" lang="en">
+  <!-- Application content -->
+</html>
+```
+
+For selective loading, import `defaults.css`, then `bridge.css`, then the
+needed `components/*.css` files. `defaults.css` owns the `--win31-*` tokens;
+the bridge maps them to shared `--rc-*` semantics. App styles outside a cascade
+layer override the theme's layered styles. Use public tokens and documented
+parts or markers; `--_rc-*` tokens and controller markers are internal.
+
+Use consumer-authored native controls where a component requires them. An
+`rc-button` contains a `<button>`; an `rc-dialog` contains a `<dialog>`; a
+`rc-disclosure` contains `<details>`. Keep native IDs, names, labels, and form
+behavior on those children. The theme changes presentation, not keyboard or
+ARIA behavior.
+
+## Apply color and typography
+
+The baseline palette in the front matter is the package's current reference
+scheme. Pair `--win31-color-selection` with
+`--win31-color-selection-text`, and each title background with its title-text
+partner. Keep the field and field-text pair legible. The desktop color is an
+application canvas choice, not an instruction to paint every page teal.
+
+Windows 3.1 exposed system color schemes rather than an automatic dark mode.
+Override the `--win31-color-*` roles together on `.rc-theme-win31`. The dither
+and arrow/check SVG tokens are separate image assets: an alternate palette may
+also need `--win31-dither-track` and `--win31-glyph-*` overrides for contrast.
+Test the result with actual controls, selected rows, a dialog, and scrollbars.
+The baseline glyphs are black. The dither follows `--win31-color-surface`,
+while color tokens alone do not recolor the glyph image assets.
+
+```css
+.rc-theme-win31.stars-like {
+  --win31-color-surface: #c3c3c3;
+  --win31-color-shadow: #828282;
+  --win31-color-title-active: #a6cbf3;
+  --win31-color-title-active-text: #000000;
+}
+```
+
+This example illustrates the originator application's palette difference; it
+is not a named Windows system scheme. The font stack prefers MS Sans Serif but
+does not ship Microsoft's bitmap font. Later system sans faces preserve
+usability while changing glyph widths and rendering.
+
+## Build period-style chrome
+
+- Use one active caption bar per window, with centered caption text and an
+  authored system-menu button when the action is real. `rc-dialog` styles a
+  direct native `<dialog>` child with an authored `<header>` and `<footer>`.
+- Put the default-button marker on `rc-button`, while keeping the actual
+  `<button>` as its direct child. The marker supplies a second frame; the native
+  button still owns its action and focus.
+- Compose menus, toolbars, listboxes, fields, and scrollbars as dense rectangular
+  regions. Use the `--win31-unit` scale for a uniformly larger interface, and
+  choose layout breakpoints in the application rather than the theme.
+- Show focus and selection independently. The dotted focus outline can coexist
+  with an inverse selected row. Do not substitute hover styling for either.
+- Preserve the disabled embossed treatment and pressed bevel reversal. The
+  theme has no general button or list-row hover treatment and no motion.
+
+```html
+<rc-dialog movable move-handle="header">
+  <dialog aria-labelledby="save-title">
+    <header>
+      <h2 id="save-title">Save Changes</h2>
+    </header>
+    <p>Save changes before closing?</p>
+    <footer>
+      <rc-button data-rc-win31-default><button type="button">OK</button></rc-button>
+      <rc-button><button type="button">Cancel</button></rc-button>
+    </footer>
+  </dialog>
+</rc-dialog>
+```
+
+The authored system-menu control needs a real menu action if shown. For a
+simple confirmation dialog, omit it. Use `data-rc-win31-inactive` on
+`rc-app-bar` only for an inactive caption, and `data-rc-win31-toggle` on
+`rc-switch` only when its optional sliding treatment suits the application.
+The default switch treatment resembles a checkbox.
+
+## Respect platform limits
+
+Browser-rendered text and native form internals will not match a 1992 bitmap
+display pixel for pixel. Detailed scrollbar chrome works in Chromium and
+WebKit; Firefox receives a two-color standard scrollbar. In forced colors the
+theme yields to system colors and removes decorative bevels. Do not restore
+custom palette colors inside that mode.
+
+`rc-fab`, `rc-fab-menu`, and several navigation or carousel patterns have no
+Windows 3.1 equivalent. Their styles keep a themed app visually coherent but
+do not make them period patterns. Prefer menu commands and toolbars when the
+application is meant to resemble a contemporary Windows 3.1 program.
+
+Tooltips did not exist in Windows 3.1 either. `rc-tooltip` borrows the WinHelp
+definition popup instead: a white box with a hard one-pixel frame and drop
+shadow. `rc-popover` uses the same menu panel as other popups, with panel
+spacing.

package/README.md

@@ -1,8 +1,160 @@
 # @rcarls/rc-theme-win31
 
-This version (`0.0.0`) is a placeholder, published only to register this package name on
-npm so a Trusted Publisher can be configured for it before any real release. It contains no code.
+Windows 3.1 era CSS theme and token bridge for
+[rc-webcomponents](https://github.com/richardcarls/rc-webcomponents).
 
-Do not install or depend on this version. The real package ships in a later version, published
-automatically through this repository's normal release pipeline once Trusted Publishing is
-configured.
+Beveled, square, motionless chrome, as Windows 3.1 looked to applications that
+linked `CTL3D`. Styling only: no component behavior changes.
+
+```sh
+npm install @rcarls/rc-theme-win31
+```
+
+```css
+@import '@rcarls/rc-theme-win31/theme.css';
+```
+
+```html
+<div class="rc-theme-win31">
+  <rc-select>...</rc-select>
+  <rc-dialog>...</rc-dialog>
+</div>
+```
+
+## Token layers
+
+`theme.css` composes three files, in this order:
+
+| File             | Owns                                                        |
+| ---------------- | ----------------------------------------------------------- |
+| `defaults.css`   | The `--win31-*` reference tokens: palette, metrics, glyphs  |
+| `bridge.css`     | The mapping from `--win31-*` onto the public `--rc-*` layer |
+| `components.css` | Per-component chrome, one stylesheet per component          |
+
+Component stylesheets read the `--win31-*` tokens with no literal fallbacks, so
+a value lives in exactly one place and cannot drift between the token layer and
+thirty-nine component sheets. Import `defaults.css` before any selective import,
+or supply the `--win31-*` set yourself.
+
+```css
+@import '@rcarls/rc-theme-win31/defaults.css';
+@import '@rcarls/rc-theme-win31/bridge.css';
+@import '@rcarls/rc-theme-win31/components/button.css';
+```
+
+Native HTML can opt into the period presentation without registering an RC
+element. Import the defaults and bridge when needed, then add the independent
+native and CSS-only layers:
+
+```css
+@import '@rcarls/rc-theme-win31/defaults.css';
+@import '@rcarls/rc-theme-win31/bridge.css';
+@import '@rcarls/rc-theme-win31/native.css';
+@import '@rcarls/rc-theme-win31/css-components.css';
+```
+
+`native.css` is an optional convenience layer for styling ordinary buttons,
+text fields, selects, textareas, checkboxes, radios, ranges, and progress
+controls throughout `.rc-theme-win31`. Component recipes style native children
+when their presentation belongs to a themed menu, toolbar, or other component
+context. Add `data-rc-native="off"` to an element to opt it and its descendants
+out of the native layer. The
+opt-in `css-components.css` recipes cover `.rc-button`, `.rc-chip`,
+`.rc-chip-group`, `.rc-select`, `.rc-textarea`, `.rc-card`, `.rc-list`, and
+`details.rc-disclosure`; each is also exported as
+`css-components/<name>.css`. They provide appearance and CSS-visible states
+only, not behavior, events, popup replacement, or measured overflow.
+
+## Scaling
+
+Every metric is a multiple of one token, so the whole theme scales without any
+proportion changing. This is the bitmap-interface answer to responsive sizing.
+
+```css
+.rc-theme-win31 {
+  --win31-unit: 2px;
+}
+```
+
+## What is deliberate
+
+- **Light only.** Windows 3.1 had no dark mode. It had user-selectable
+  whole-system color schemes instead. Override the `--win31-color-*` roles as
+  a set; the dither follows the surface token, while the baseline glyph SVGs
+  remain black and may need replacement for a contrasting scheme. Named period
+  schemes are not shipped without verified values.
+- **No hover states**, except on menus. That is period-correct and it does
+  surprise people. Push buttons and list rows are identical at rest and under
+  the pointer. The upside is that every affordance is legible without a pointer,
+  which is what touch and keyboard users need anyway.
+- **Disabled is a color, not an opacity.** 3.1 had no alpha channel, so it
+  embossed disabled text: gray with a one-pixel highlight beneath. WCAG exempts
+  inactive controls from the contrast minimum, so the period treatment stands.
+- **Focus and selection are separate marks.** A list can hold a selected row
+  that is not the focused row, so the dotted focus rectangle is drawn in
+  addition to the inverse-video selection, and turns white inside it.
+- **It disappears under forced colors.** Every bevel is an inset shadow, a
+  four-value `border-color`, or a dither image, and High Contrast removes all
+  three. The theme yields completely. The result is closer to stock, pre-`CTL3D`
+  Windows 3.1 than the beveled default is.
+- **Scrollbar chrome is Chromium and WebKit only.** Firefox exposes only
+  `scrollbar-width` and `scrollbar-color`, so it gets a two-color fallback.
+- **`rc-fab` and `rc-fab-menu` are knowing anachronisms.** Windows 3.1 had no
+  floating action button and nothing that would have produced one. They are
+  drawn as floating tool-palette buttons so a themed page has no unstyled
+  holes.
+
+## Window chrome
+
+`rc-dialog` keeps the native `<dialog>` in consumer light DOM, so the caption
+bar is your markup. The theme styles the shape the component already contracts
+on through `move-handle`:
+
+```html
+<rc-dialog movable move-handle="header">
+  <dialog aria-labelledby="save-title">
+    <header>
+      <h2 id="save-title">Save Changes</h2>
+    </header>
+    <p>Save changes before closing?</p>
+    <footer>
+      <rc-button data-rc-win31-default><button>OK</button></rc-button>
+      <rc-button><button>Cancel</button></rc-button>
+    </footer>
+  </dialog>
+</rc-dialog>
+```
+
+## Theme markers
+
+Three authored markers are public API for this theme:
+
+| Marker                   | Applies to   | Effect                                         |
+| ------------------------ | ------------ | ---------------------------------------------- |
+| `data-rc-win31-default`  | `rc-button`  | The heavier frame of a dialog's default button |
+| `data-rc-win31-toggle`   | `rc-switch`  | The sliding variant instead of the checkbox    |
+| `data-rc-win31-inactive` | `rc-app-bar` | The muted inactive caption pair                |
+
+## Fonts
+
+MS Sans Serif is a Microsoft bitmap face and is not redistributed here. The
+stack falls back through `Tahoma` and the system sans, so type is
+metric-adjacent rather than pixel-exact.
+
+## Notice
+
+Not affiliated with or endorsed by Microsoft. Windows is a trademark of
+Microsoft Corporation. No Microsoft fonts, bitmaps, or icons are redistributed;
+every glyph in this package is redrawn as SVG or CSS.
+
+## Documentation
+
+- [`DESIGN.md`](./DESIGN.md) gives composition guidance, historical sources,
+  and the limits of the web recreation. It ships as
+  `@rcarls/rc-theme-win31/DESIGN.md` for package-aware tools.
+- [Theme previews](https://richardcarls.github.io/rc-webcomponents/guide/theme-previews)
+- [Styling guide](https://richardcarls.github.io/rc-webcomponents/guide/styling)
+
+## License
+
+MIT