From 254b443c6132f3a6ad76cb0fd7a452147f7f5caa Mon Sep 17 00:00:00 2001 From: konojunya Date: Sun, 6 Sep 2026 12:48:43 +0900 Subject: [PATCH] docs: make the README reader-first --- README.md | 24 +++++++++++++++++++++--- crates/stack-theme/README.md | 2 +- packages/theme/README.md | 2 +- 3 files changed, 23 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 260ecf0..3d61d82 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ `stack-sh/theme` is the canonical public contract for Stack diagram themes, icons, font metrics, and local provider icon packs. -The draft core catalog contract is defined by [`CONTRACT.md`](./CONTRACT.md) and [`schemas/catalog.schema.json`](./schemas/catalog.schema.json). The separate local-only provider-pack contract is defined by [`PROVIDER_PACKS.md`](./PROVIDER_PACKS.md) and [`schemas/provider-pack.schema.json`](./schemas/provider-pack.schema.json). The canonical core source is [`catalog/catalog.json`](./catalog/catalog.json); Cargo and npm artifacts are generated from that source with one content revision. +The core catalog contract is defined by [`CONTRACT.md`](./CONTRACT.md) and [`schemas/catalog.schema.json`](./schemas/catalog.schema.json). The separate local-only provider-pack contract is defined by [`PROVIDER_PACKS.md`](./PROVIDER_PACKS.md) and [`schemas/provider-pack.schema.json`](./schemas/provider-pack.schema.json). The canonical core source is [`catalog/catalog.json`](./catalog/catalog.json); Rust and JavaScript package trees are generated from that source with one content revision. The current `0.6.0` catalog contains the core `default`, `light`, and `dark` themes, repository-authored fallbacks for every Stack 1.0 node kind, 30 provider-neutral explicit icons, and versioned host-independent font metrics. The explicit icon catalog covers clients and compute, networking and delivery, data and events, development workflows, security, general collaboration tools, and AI systems. Its identifiers are `api`, `web`, `mobile`, `desktop`, `server`, `container`, `cluster`, `cloud`, `scheduler`, `webhook`, `identity`, `observability`, `gateway`, `load-balancer`, `dns`, `cdn`, `firewall`, `network`, `event`, `stream`, `search`, `analytics`, `repository`, `pipeline`, `secret`, `document`, `task`, `chat`, `email`, and `ai`. @@ -18,14 +18,32 @@ cargo add stack-theme@0.6.0 The package supports Rust 1.85 or newer and includes only the generated catalog API, repository-authored SVG assets, public schemas, package documentation, and the Apache-2.0 license. +Read a core theme and its semantic color tokens without filesystem or network access: + +```rust +fn main() { + let catalog = stack_theme::catalog(); + let default_theme = catalog.themes.iter().find(|theme| theme.id == "default"); + + assert_eq!(catalog.catalog_version, stack_theme::CATALOG_VERSION); + assert!(default_theme.is_some()); +} +``` + +See the complete [`stack-theme` API documentation](https://docs.rs/stack-theme). + +## Distribution + +`stack-theme` is published on crates.io. The repository also generates `packages/theme` to verify Rust/JavaScript semantic parity and to supply the browser Engine build, but `@stack-sh/theme` is not currently published as a standalone npm package. Browser applications should normally install [`@stack-sh/engine`](https://www.npmjs.com/package/@stack-sh/engine), which embeds the matching catalog. + ## Scope -This repository will own: +This repository owns: - the versioned core theme catalog; - icon metadata and SVG-safe icon assets; - deterministic font metrics used by the layout engine; -- equivalent Rust and npm artifacts generated from the same catalog data. +- equivalent Rust and JavaScript package trees generated from the same catalog data; - a provider-neutral manifest and validation contract for user-imported vendor icons. It does not own the Stack language, compilation, layout, SVG rendering, user authentication, billing, entitlement checks, or paid-theme delivery. diff --git a/crates/stack-theme/README.md b/crates/stack-theme/README.md index 4ecfdc4..70141a7 100644 --- a/crates/stack-theme/README.md +++ b/crates/stack-theme/README.md @@ -4,4 +4,4 @@ The public contract and compatibility policy are documented in the repository's [`CONTRACT.md`](https://github.com/stack-sh/theme/blob/main/CONTRACT.md). -Add version 0.5.0 from crates.io with `cargo add stack-theme@0.5.0`. The package supports Rust 1.85 or newer. +Add version 0.6.0 from crates.io with `cargo add stack-theme@0.6.0`. The package supports Rust 1.85 or newer. diff --git a/packages/theme/README.md b/packages/theme/README.md index 7457794..9dd52a3 100644 --- a/packages/theme/README.md +++ b/packages/theme/README.md @@ -4,6 +4,6 @@ The package is browser-safe and performs no filesystem, network, clock, locale, or host-font access. See the repository's [`CONTRACT.md`](https://github.com/stack-sh/theme/blob/main/CONTRACT.md) for the core catalog and [`PROVIDER_PACKS.md`](https://github.com/stack-sh/theme/blob/main/PROVIDER_PACKS.md) for the local provider-pack contract. -Catalog `0.4.0` includes 30 provider-neutral explicit icons shared by the `default`, `light`, and `dark` themes: `api`, `web`, `mobile`, `desktop`, `server`, `container`, `cluster`, `cloud`, `scheduler`, `webhook`, `identity`, `observability`, `gateway`, `load-balancer`, `dns`, `cdn`, `firewall`, `network`, `event`, `stream`, `search`, `analytics`, `repository`, `pipeline`, `secret`, `document`, `task`, `chat`, `email`, and `ai`. Resolve a core icon's catalog asset path through `iconSvg()`; do not treat a logical icon identifier as a filesystem path or URL. +Catalog `0.6.0` includes 30 provider-neutral explicit icons shared by the `default`, `light`, and `dark` themes: `api`, `web`, `mobile`, `desktop`, `server`, `container`, `cluster`, `cloud`, `scheduler`, `webhook`, `identity`, `observability`, `gateway`, `load-balancer`, `dns`, `cdn`, `firewall`, `network`, `event`, `stream`, `search`, `analytics`, `repository`, `pipeline`, `secret`, `document`, `task`, `chat`, `email`, and `ai`. Resolve a core icon's catalog asset path through `iconSvg()`; do not treat a logical icon identifier as a filesystem path or URL. `providerPackSchema` describes manifests produced from a provider archive that the user explicitly imports. It requires local-only processing, disabled package redistribution, provider-prefixed icon IDs, source and processed hashes, artwork-preservation policy, and user-visible terms notices. The package contains no vendor asset bytes and never downloads or uploads an archive.