From 5c75b316a71ec876cd64c46a5205a163ca4f39dc Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Sun, 11 Oct 2026 18:23:09 +0200 Subject: [PATCH] docs(17): UI design contract --- .../phases/17-blog-companions/17-UI-SPEC.md | 815 ++++++++++++++++++ 1 file changed, 815 insertions(+) create mode 100644 .planning/phases/17-blog-companions/17-UI-SPEC.md diff --git a/.planning/phases/17-blog-companions/17-UI-SPEC.md b/.planning/phases/17-blog-companions/17-UI-SPEC.md new file mode 100644 index 0000000..ab54161 --- /dev/null +++ b/.planning/phases/17-blog-companions/17-UI-SPEC.md @@ -0,0 +1,815 @@ +--- +phase: "17" +slug: "blog-companions" +status: approved +reviewed_at: "2026-10-11" +shadcn_initialized: false +preset: none +created: "2026-10-11" +--- + +# Phase 17 — UI Design Contract + +> Visual and interaction contract for frontend phases. Generated by msd-ui-researcher, verified by msd-ui-checker. + +This phase has three visual surfaces: + +1. **Admin SPA (`admin/`, framework).** Four generic cabana features (D-06 to D-10) and one view variant: + - the `richeditor` field (HTML WYSIWYG); + - the `repeater` field; + - the dependent dropdown (`dependsOn`); + - the tree reorder page, reached from a new list heading button; + - the singleton form, which opens the one sitemap definition directly (D-11). +2. **Plugin admin screens** of `sm-faq-plugin`, `sm-menu-plugin` and `sm-sitemap-plugin`. They are YAML only (`fields.yaml`, `columns.yaml`, settings fields) and have no plugin Vue code. They render through the existing list, form and settings views plus the features above. +3. **Two Nuxt layers, `vue-menu-layer` and `vue-faq-layer` (D-18).** They are neutral, token-driven render components in the `vue-journal-layer` style. The site app overrides their tokens or components. + +`sitemap.xml` and `sitemap.xsl` have **no new visual design**. The XSL is embedded byte-identical to the PHP `assets/sitemap.xsl`, so the browser view of the sitemap stays the PHP presentation (D-14, RESEARCH Pattern 4). + +The admin SPA already has a complete design system: Direction C v2 (`.planning/phases/10-admin-vue-spa/design/README.md`), implemented as Tailwind 4 `@theme` tokens in `admin/src/styles/main.css` on Reka UI primitives. **This contract adds no new admin tokens, colours, fonts, radii or shadows.** Every admin value below reuses an existing token or copies a class string from an existing component: `FormView.vue`, `ListView.vue`, `FormField.vue`, `FormGrid.vue`, `DropdownField.vue`, `MarkdownField.vue`, `FileuploadField.vue`, `Button.vue`, `control.ts`, and the 12.2 and 16.3 UI-SPECs. + +Sources: +- `17-CONTEXT.md`: D-05, D-07 to D-11, D-13, D-16 to D-18 (locked). +- `17-RESEARCH.md`: Patterns 5 to 10, Pitfalls 9, 10 and 15, Assumptions A1, A4 and A6 to A8. +- Phase 12.2 and 16.3 UI-SPECs (approved house conventions). +- The codebase scan listed above. +- The PHP port sources: `faq/models/faq/fields.yaml`; `menu/models/{menu,menuentry}/fields.yaml`, `menuentries/_list_toolbar.php` and `reorder_config.yaml`; `sitemap/classes/definitionitem/fields.yaml`, `models/settings/fields.yaml` and `lang/{en,pl}`; `themes/arsha/partials/g15_menu`, `g15_faq`. +- The current site markup the layers replace: `vue-grzybyfunkcjonalne-app/app/components/{SiteHeader,FaqSection}.vue`. + +**Out of this contract:** +- Journal's category `content` field stays `type: blogeditor` (the Phase 16.2 Blog Editor). RESEARCH A1 recommends dropping D-10's "switch to richeditor" clause, and this contract specifies no change to it; the user confirms during planning. +- The production cutover. + +--- + +## Design System + +| Property | Value | +|----------|-------| +| Tool | none. There is no shadcn: this is a Vue 3 SPA with its own Direction C system. The shadcn gate does not apply to a Vue codebase with an established system, the same ruling as Phases 10.1, 12.1, 12.2 and 16.3. The Nuxt layers use plain scoped CSS on their own tokens, like `vue-journal-layer`. | +| Preset | not applicable | +| Component library | Admin: Reka UI 2.9.10 (headless primitives) plus the local components in `admin/src/components/`. Layers: none (Vue SFCs with native `
`, `