From 682697d7abebd7d994b85ca275498ba23016dc7b Mon Sep 17 00:00:00 2001 From: crazyracer98 <8631139+crazyracer98@users.noreply.github.com> Date: Mon, 26 Oct 2026 07:26:34 +0000 Subject: [PATCH] docs: record outcomes of the templates/SDKs/UI work (DOC1) - ADR 0003-0006: drop references to the working plan; ADR 0006 states the final crud-sdk/crud-views 0.5.x wiring, loopback rule and view choices - design workflow: why the loop exists --- .../0003-re-parent-onto-template-docker.md | 2 +- .../adrs/0004-design-system-and-token-lint.md | 2 +- ...005-storybook-visual-regression-and-axe.md | 6 ++--- docs/adrs/0006-manifest-driven-admin.md | 25 +++++++++++++------ docs/design/workflow.md | 7 ++++++ 5 files changed, 29 insertions(+), 13 deletions(-) diff --git a/docs/adrs/0003-re-parent-onto-template-docker.md b/docs/adrs/0003-re-parent-onto-template-docker.md index c4a9f75..37313e4 100644 --- a/docs/adrs/0003-re-parent-onto-template-docker.md +++ b/docs/adrs/0003-re-parent-onto-template-docker.md @@ -16,7 +16,7 @@ devcontainer image lives in `.devcontainer/Dockerfile`, the top-level `Dockerfile` is the instance's runtime image, and a template-owned `Makefile` implements the release contract (OCI build, SBOM, labels, smoke test, publish of the tested tar with skopeo) tuned by an optional instance-owned `image.mk` -(its ADR 0001). Track UI of `docs/plans/2026-10-templates-sdks-ui.md` also needs +(its ADR 0001). The UI layer also needs Storybook, Playwright, axe, Motion, self-hosted fonts and TanStack Query, and wants them, with the lockfile, in one reviewable change before the items that use them (UI1 onward) run in parallel. diff --git a/docs/adrs/0004-design-system-and-token-lint.md b/docs/adrs/0004-design-system-and-token-lint.md index 32c36cf..ac9b950 100644 --- a/docs/adrs/0004-design-system-and-token-lint.md +++ b/docs/adrs/0004-design-system-and-token-lint.md @@ -6,7 +6,7 @@ Accepted ## Context -Track UI of `docs/plans/2026-10-templates-sdks-ui.md` wants a UI that does +This template wants a UI that does not look like default model output (Roboto/Inter, purple gradients, no motion) and stays consistent as Claude and people add screens. The user picked aesthetic direction A, "Field Ledger", from three RS3 prototypes diff --git a/docs/adrs/0005-storybook-visual-regression-and-axe.md b/docs/adrs/0005-storybook-visual-regression-and-axe.md index 5534c81..3c1f0b6 100644 --- a/docs/adrs/0005-storybook-visual-regression-and-axe.md +++ b/docs/adrs/0005-storybook-visual-regression-and-axe.md @@ -6,13 +6,13 @@ Accepted ## Context -Track UI of `docs/plans/2026-10-templates-sdks-ui.md` wants every component -visible in isolation and a pass/fail signal for how it looks, so that neither +Every component should be +visible in isolation, and how it looks needs a pass/fail signal, so that neither a person nor Claude can change the Field Ledger system (ADR 0004) without noticing. Pixel baselines are only worth having if the same inputs always give the same pixels, and CI has to reproduce what a developer generated locally. -The plan said to generate baselines "in the toolchain container against the +The first idea was to generate baselines "in the toolchain container against the stack's Chromium". Two things stood in the way. The stack's Selenium Grid cannot be driven by Playwright: its CDP endpoint answers `ws://selenium:4444/.../se/cdp` with HTTP 400 (found in UI1 and UI2), and `toHaveScreenshot` needs Playwright's diff --git a/docs/adrs/0006-manifest-driven-admin.md b/docs/adrs/0006-manifest-driven-admin.md index eb37613..499b761 100644 --- a/docs/adrs/0006-manifest-driven-admin.md +++ b/docs/adrs/0006-manifest-driven-admin.md @@ -13,8 +13,7 @@ now publishes a CRUD manifest (template-fastapi ADR 0025) that describes every resource a caller may see: fields, filter operators, capabilities, paths and limits. Two libraries consume it: `@craftainer/crud-sdk` (typed client, ETag cache, TanStack Query helpers) and `@craftainer/crud-views` (MUI views for -list, form, detail, revisions, trash, statistics and predictions). The plan -(`docs/plans/2026-10-templates-sdks-ui.md`, item UI4) has this template use +list, form, detail, revisions, trash, statistics and predictions). This template uses both. Four facts about the libraries and the app shaped the wiring: @@ -42,6 +41,15 @@ Four facts about the libraries and the app shaped the wiring: the trash. Nothing in it names the Hero model. System fields (ids, owner, lifecycle and audit timestamps) are left out of the table and shown on the record page. +- **Which views.** The admin composes the view families `@craftainer/crud-views` + ships (list, filter, sort, form, delete, detail, revisions, bulk, + draft/publish, archive, statistics, predictions). The variants of each were + chosen from a survey of react-admin, Refine, MUI Toolpad and shadcn blocks, + keeping what MUI's MIT tier can build (so no multi-sort, calendar or Pro + grid features) and what the manifest can drive (so no related-record + editing: the manifest has no relations yet). The admin picks the plain + variants (paged table, form in the record page, confirm-before-delete); a + derived app picks others per page from the library's props. - **Client wiring** (`src/api/sdk.ts`, `src/api/CrudApi.tsx`). The client's `baseUrl` is the page origin and its `fetch` puts every same-origin URL under `/api`. The token provider reads the OIDC session and calls `signinSilent()` @@ -83,12 +91,13 @@ Four facts about the libraries and the app shaped the wiring: and the SDK's `client.namespace()` (`"anon"`) otherwise, because crud-views resolves the namespace once per client and does not watch the token. The SDK 0.5.0 throws `InsecureTransportError` before sending a request that - carries a token over plain http to a non-loopback host; the client's base URL - is the page's own origin, so this only bites when the app is served over http - from a non-loopback host, and `allowInsecureHttp` is deliberately not set. - (Written against 0.4.0 and re-checked against SDK 0.5.1 / views 0.5.1 on - upgrade; views 0.5 reads the key field from `resource.id_field`, which the - manifest already supplies.) The `@craftainer/*` scope is excluded from pnpm's + carries a token over plain http to a non-loopback host (loopback hosts such as + `localhost` are exempt, so local development works over http); the client's + base URL is the page's own origin, so this only bites when the app is served + over http from a non-loopback host, and `allowInsecureHttp` is deliberately + not set: a deployment that serves the app without TLS should fix that rather + than opt in. Views 0.5 reads the key field from `resource.id_field`, which the + manifest supplies, so a resource whose id is not called `id` works. The `@craftainer/*` scope is excluded from pnpm's `minimumReleaseAge` (user decision, 2026-10-24): we release these ourselves and consume them right away. - **Tests.** Unit tests cover the `/api` prefixing, discovery, the cached ETag diff --git a/docs/design/workflow.md b/docs/design/workflow.md index f048b2a..d41a098 100644 --- a/docs/design/workflow.md +++ b/docs/design/workflow.md @@ -7,6 +7,13 @@ the manifest-driven admin itself see [ADR 0006](../adrs/0006-manifest-driven-admin.md), which this page does not repeat. +Why a workflow and not just a style guide: models default to generic output +(Inter, purple gradients, minimal motion) unless they are given a specific +direction, the real component library, one place for tokens with a lint, and a +way to see what they built. Each step below supplies one of those, and the +guidance steps load only when a UI task needs them rather than sitting in every +prompt. + ## The loop | Step | What | Enforced by | Runs |