@redspartanlabs/spartacss 1.0.3 → 1.0.4

package/CHANGELOG.md

@@ -6,6 +6,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 per ADR-0001.
 
+## [1.0.4] - 2026-10-09
+
+### Added
+
+- [ADR-0007](docs/adr/0007-documentation-preview-contract.md), which defines
+  how a documentation page designates one HTML example for optional live
+  rendering: the fence info string `html preview`. The marker grants
+  permission and requires nothing of a consumer, a page has at most one, and
+  consumers must not infer a live example any other way.
+- Section 15.8 of the component standard, stating the authoring rule for the
+  marker.
+- `scripts/verify-docs-preview.mjs`, run by `npm run verify`, which checks the
+  marker, the one-per-page limit and the content rules. `RELEASING.md` runs it
+  against the extracted release package.
+
+### Changed
+
+- The Size example on the Button page carries the marker. The page renders as
+  before.
+- The Decisions table in the documentation index now lists ADR-0005, ADR-0006
+  and ADR-0007.
+
+This release changes documentation and the release procedure only. No public
+class selector, modifier, design token, markup contract or `exports` entry
+point changed, no shipped CSS output changed, and the package whitelist is
+unchanged — a non-breaking, patch-level change per ADR-0002. The package gains
+ADR-0007 under `docs/adr/`.
+
 ## [1.0.3] - 2026-10-09
 
 ### Added
@@ -481,7 +509,8 @@ output changed — a non-breaking, patch-level change per ADR-0002.
   system; ownership confirmed as belonging to the icon system, duplicate
   block removed from core.
 
-[Unreleased]: https://github.com/redspartanlabs/spartacss/compare/v1.0.3...HEAD
+[Unreleased]: https://github.com/redspartanlabs/spartacss/compare/v1.0.4...HEAD
+[1.0.4]: https://github.com/redspartanlabs/spartacss/compare/v1.0.3...v1.0.4
 [1.0.3]: https://github.com/redspartanlabs/spartacss/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/redspartanlabs/spartacss/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/redspartanlabs/spartacss/compare/v1.0.0...v1.0.1

package/README.md

@@ -10,7 +10,7 @@ no framework bindings, usable from any site or app regardless of stack.
 **[→ Documentation index](docs/README.md)** — components, tokens, theming,
 layout, motion, accessibility, and the architecture decisions behind them.
 
-**Status:** the package is at `1.0.3`. Its intended registry is npm, as
+**Status:** the package is at `1.0.4`. Its intended registry is npm, as
 `@redspartanlabs/spartacss`
 ([ADR-0006](docs/adr/0006-npm-registry-distribution.md)), and `1.0.3` is the
 first release intended for it; `1.0.2` was a GitHub-only release, not intended
@@ -31,7 +31,7 @@ none of that documentation is repeated here.
 **1. Install.** A tag-pinned git dependency (see [Installation](#installation)):
 
 ```
-npm install github:redspartanlabs/spartacss#v1.0.3
+npm install github:redspartanlabs/spartacss#v1.0.4
 ```
 
 **2. Import a bundle.** One line gets you the default bundle — tokens,
@@ -74,7 +74,7 @@ SpartaCSS is intended for distribution on npm as `@redspartanlabs/spartacss`
 a tag-pinned git dependency, per ADR-0001's phased distribution plan:
 
 ```
-npm install github:redspartanlabs/spartacss#v1.0.3
+npm install github:redspartanlabs/spartacss#v1.0.4
 ```
 
 `1.0.3` is the first release intended for npm. Where the registry has it,

package/RELEASING.md

@@ -191,6 +191,18 @@ every file that Git tracks at the tag under the paths in `package.json`'s
 node -e "const{execSync}=require('child_process'),fs=require('fs');const j=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));const p=Array.isArray(j)?j[0]:Object.values(j)[0];const actual=p.files.map(f=>f.path).sort();const pj=JSON.parse(execSync('git show '+process.argv[2]+':package.json',{encoding:'utf8'}));const paths=[...new Set([...pj.files,'package.json','README.md','LICENSE'])];const expected=execSync('git ls-tree -r --name-only '+process.argv[2]+' -- '+paths.join(' '),{encoding:'utf8'}).split(/\r?\n/).filter(Boolean).sort();const missing=expected.filter(f=>!actual.includes(f)),unexpected=actual.filter(f=>!expected.includes(f));console.log('expected',expected.length,'packed',actual.length,'missing',JSON.stringify(missing),'unexpected',JSON.stringify(unexpected));process.exit(missing.length||unexpected.length?1:0)" <directory>/pack.json vX.Y.Z
 ```
 
+**Check the documentation contract.** `npm run verify` has already checked the
+working tree. Check the package itself too: extract the tarball into an empty
+directory outside the repository (for example by running
+`tar -xzf <tarball>` from inside that directory), then run this from the
+repository root:
+
+```
+node scripts/verify-docs-preview.mjs <empty directory>/package
+```
+
+It must print `OK`. Any other result means stop and report.
+
 It prints the expected and packed counts, the files missing from the package
 and the unexpected files in it, and exits non-zero unless both lists are empty.
 Any missing or unexpected file means stop. Because `npm pack` also packs

package/docs/README.md

@@ -98,6 +98,9 @@ above does not settle.
 | [ADR-0002](adr/0002-versioning-and-stability-policy.md) | What counts as a breaking change for a pure-CSS design system. Read this before depending on a class name. |
 | [ADR-0003](adr/0003-independent-iconography-system.md) | Why the iconography system is SpartaCSS's own. |
 | [ADR-0004](adr/0004-git-tag-artifact-distribution.md) | Why release tags carry prebuilt `dist/` artifacts. |
+| [ADR-0005](adr/0005-canonical-ui-component-standard.md) | The canonical UI component standard: why it exists and what it leaves open. Still Proposed. |
+| [ADR-0006](adr/0006-npm-registry-distribution.md) | npm as the intended registry, under `@redspartanlabs/spartacss`, with GitHub as the canonical home. |
+| [ADR-0007](adr/0007-documentation-preview-contract.md) | How a documentation page designates one HTML example for optional live rendering. |
 
 Release history lives in [CHANGELOG.md](../CHANGELOG.md); the procedure for
 cutting a release is [RELEASING.md](../RELEASING.md).

package/docs/adr/0007-documentation-preview-contract.md

@@ -0,0 +1,106 @@
+# ADR-0007: Documentation Preview Contract
+
+**Status:** Accepted (2026-10-09)
+
+---
+
+## Context
+
+SpartaCSS documentation pages show HTML examples in fenced code blocks. A
+consumer of the documentation, such as a documentation site, may want to render
+one of those examples live beside its source. Nothing in the documentation says
+which example is meant for that. A consumer left to guess would infer it from
+fence order, headings or metadata of its own, and each of those changes
+silently when a page is edited.
+
+This record lets a page designate an example explicitly, in the page itself. It
+is a documentation convention. It changes no CSS, selector, token or export
+(see ADR-0002), and it requires nothing of any consumer.
+
+---
+
+## Decision
+
+1. **The marker.** A fenced code block is designated for optional live
+   rendering when its info string is the language identifier `html` followed by
+   the token `preview`:
+
+   ````markdown
+   ```html preview
+   <button class="sp-button sp-button--primary sp-button--sm">Small</button>
+   <button class="sp-button sp-button--primary sp-button--md">Medium (default)</button>
+   <button class="sp-button sp-button--primary sp-button--lg">Large</button>
+   ```
+   ````
+
+   Whitespace between the two words is not significant. A fence is a marker
+   only in this form. A `preview` token in any other form is malformed: a
+   different language, a different letter case, or any additional token.
+   Verification rejects a malformed marker instead of ignoring it. Other
+   tokens in the info string are reserved.
+2. **Permission, not requirement.** The marker permits a consumer to render the
+   example live. It does not require any consumer to do so, and a consumer that
+   does not is unaffected.
+3. **One per page.** A page contains at most one marked example.
+4. **Content.** A marked example is a standalone HTML fragment. It is
+   non-empty, it is not a whole document (`<!doctype>`, `<html>`, `<head>` or
+   `<body>`), it contains no `<script>` element, and none of its link targets
+   (`href`, `src`, `action`, `formaction`, `poster`) is site-relative. A link
+   target is site-relative when it is neither an absolute URL with a scheme nor
+   a fragment-only reference. It also depends on no other content of its page.
+5. **Rendering is unchanged.** The marker extends only the info string. The
+   language remains `html`, so a conforming Markdown renderer presents the block
+   as it did before.
+6. **No inference.** A consumer must not infer a live example from fence
+   position, from headings, or from metadata it keeps itself. An example is
+   eligible for live rendering only if it carries the marker.
+7. **Enforcement and first use.** `scripts/verify-docs-preview.mjs`, run by
+   `npm run verify`, applies decisions 1, 3 and 4 to every Markdown page under
+   `docs/`, except that it cannot check by machine that an example depends on
+   no other content of its page. It also requires the pages it names to carry
+   their marker. The first is the Size example on the Button page. The release
+   procedure in `RELEASING.md` runs the same script against the extracted
+   release package.
+
+---
+
+## Relationship to other records
+
+This record adds a documentation convention and does not change what ADR-0002
+treats as a breaking change. Adding a marker to a page is a documentation
+change. The authoring rule for component pages appears in section 15.8 of the
+component standard (ADR-0005, still Proposed). That section states the rule,
+and this record is the decision behind it. No existing record is amended.
+
+---
+
+## Consequences
+
+**Benefits**
+- A consumer can render a live example without guessing, and the choice is
+  visible in the page and reviewable in its diff.
+- The marker survives edits that reorder a page, because it travels with the
+  example.
+- Pages render as they did before.
+
+**Tradeoffs**
+- A page can designate only one example.
+- Verification checks the properties listed in decisions 1, 3 and 4. Whether an
+  example is truly standalone, and whether it looks right when rendered, remain
+  the author's and reviewer's responsibility.
+- A consumer whose Markdown tool treats the whole info string as the language
+  name must read only its first word.
+
+**Maintenance implications**
+- A page that gains a marker is added to the pages `scripts/verify-docs-preview.mjs`
+  requires only when a consumer depends on it.
+
+---
+
+## Future ADRs / Decisions
+
+- **Other languages or several previews per page** — not decided. The marker
+  covers one `html` example per page.
+- **Further info-string tokens** — reserved and not defined here.
+- **Which further pages carry a marker** — decided page by page, not by this
+  record.

package/docs/button.md

@@ -24,7 +24,7 @@ activation (see Accessibility below).
 
 ### Size
 
-```html
+```html preview
 <button class="sp-button sp-button--primary sp-button--sm">Small</button>
 <button class="sp-button sp-button--primary sp-button--md">Medium (default)</button>
 <button class="sp-button sp-button--primary sp-button--lg">Large</button>

package/docs/design/component-standard.md

@@ -622,6 +622,33 @@ they apply**:
   Components consume global tokens and have no component token API to list;
   [`tokens.md`](../tokens.md) documents the tokens.
 
+### 15.8 Live examples
+
+A page **MAY** designate one HTML example for optional live rendering by
+consumers of the documentation. The decision is recorded in
+[ADR-0007](../adr/0007-documentation-preview-contract.md).
+
+- A page designates an example only with the marker: the info string of the
+  example's fenced code block is `html preview`.
+
+  ````markdown
+  ```html preview
+  <button class="sp-button sp-button--primary">Save</button>
+  ```
+  ````
+
+- A page **MUST NOT** contain more than one marked example.
+- A marked example **MUST** be a standalone HTML fragment: non-empty, not a
+  whole document, without a `<script>` element, and without site-relative link
+  targets. It **MUST NOT** depend on other content of its page.
+- The marker grants permission and nothing more. A page **MUST** still present
+  the example's code and explanation as ordinary documentation, and **MUST
+  NOT** rely on any consumer rendering the example.
+- A `preview` token in any other form (another language, another letter case,
+  or an additional token) is malformed and **MUST NOT** appear.
+- `scripts/verify-docs-preview.mjs`, run by `npm run verify`, checks the
+  marker, the one-per-page limit and the content rules above.
+
 ---
 
 ## 16. Stability status

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redspartanlabs/spartacss",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "A framework-agnostic CSS design system built for systems that must last.",
   "license": "Apache-2.0",
   "repository": {
@@ -42,7 +42,7 @@
     "build:bundle": "node -e \"require('fs').mkdirSync('dist',{recursive:true})\" && lightningcss --bundle src/sparta.css -o dist/sparta.css && lightningcss --bundle src/spartacss.css -o dist/spartacss.css && lightningcss --bundle src/sparta-all.css -o dist/sparta-all.css && node -e \"require('fs').copyFileSync('src/modules/icons/sparta-icons.css','dist/sparta-icons.css')\" && node -e \"require('fs').copyFileSync('src/modules/feedback/sparta-notifications.css','dist/sparta-notifications.css')\"",
     "build:minify": "lightningcss --bundle --minify src/sparta.css -o dist/sparta.min.css && lightningcss --bundle --minify src/spartacss.css -o dist/spartacss.min.css && lightningcss --bundle --minify src/sparta-all.css -o dist/sparta-all.min.css && lightningcss --minify src/modules/icons/sparta-icons.css -o dist/sparta-icons.min.css && lightningcss --minify src/modules/feedback/sparta-notifications.css -o dist/sparta-notifications.min.css",
     "build": "npm run build:bundle && npm run build:minify",
-    "verify": "node scripts/verify-legacy-bundle.mjs",
+    "verify": "node scripts/verify-legacy-bundle.mjs && node scripts/verify-docs-preview.mjs",
     "verify:artifact": "node scripts/verify-release-artifact.mjs"
   },
   "devDependencies": {