@cogito.ai/astryx-web 0.1.0 → 0.2.0

package/bin/astryx-web.mjs

@@ -2,10 +2,10 @@
 
 import { spawn, spawnSync } from 'node:child_process'
 import { once } from 'node:events'
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { fileURLToPath } from 'node:url'
 
 const COMMAND = 'samples'
 const APPEARANCE_STORAGE_KEY = 'agentdock.appearance'
@@ -345,6 +345,9 @@ async function main() {
   }
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (
+  process.argv[1] &&
+  realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+) {
   await main()
 }

package/docs/dock-style-archetypes.doc.mjs

@@ -0,0 +1,104 @@
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export default {
+  type: "generic",
+  name: "dock-style-archetypes",
+  title: "Dock Style Archetypes",
+  description: "Eight approved visual directions built on Astryx themes.",
+  sections: [
+    {
+      title: "Style archetypes",
+      content: [
+        {
+          type: "prose",
+          text: "The design discussion may only propose directions from this table. Reference brands describe a look; never copy their fonts, logos, or assets.",
+        },
+        {
+          type: "table",
+          headers: [
+            "Id",
+            "Base theme",
+            "Temperament",
+            "Color strategy",
+            "Type, density, radius",
+            "Suits",
+            "Look reference",
+          ],
+          rows: [
+            [
+              "quiet-tool",
+              "neutral",
+              "calm, focused, efficient",
+              "about 90% neutral; one accent for the primary action and focus only",
+              "system sans; compact; small radii",
+              "editors, studios, productivity tools",
+              "Linear, Figma",
+            ],
+            [
+              "warm-learning",
+              "butter",
+              "friendly, encouraging, light",
+              "warm surfaces, one blue accent; clear success and error states",
+              "rounded sans; comfortable; medium radii",
+              "learning and practice, habits",
+              "Duolingo (restrained), Headspace",
+            ],
+            [
+              "calm-content",
+              "matcha",
+              "natural, steady, trustworthy",
+              "low-saturation green and neutrals; few accents",
+              "readable body type; generous spacing",
+              "wellness, reading, content-first",
+              "Calm, Notion",
+            ],
+            [
+              "crafted-record",
+              "stone",
+              "plain, reliable, warm",
+              "warm grey and slate; a low-saturation accent",
+              "sans; comfortable; medium radii",
+              "records, archives, personal management",
+              "Things, Bear",
+            ],
+            [
+              "editorial",
+              "gothic",
+              "serious, memorable",
+              "deep blue-grey; display serif headings",
+              "serif display with sans body; spacious",
+              "reports, portfolios, long-form",
+              "Medium, The Atlantic",
+            ],
+            [
+              "warm-premium",
+              "chocolate",
+              "rich, refined",
+              "brown palette; serif headings",
+              "the theme's Fraunces and Albert Sans; spacious",
+              "lifestyle, premium content",
+              "Aesop, Kinfolk",
+            ],
+            [
+              "playful",
+              "y2k",
+              "bubbly, young",
+              "saturated pink and lime, used sparingly",
+              "the theme's Poppins; comfortable; large radii",
+              "kids, entertainment, community",
+              "—",
+            ],
+            [
+              "precise-data",
+              "neutral with a blue brand color",
+              "exact, credible",
+              "neutrals plus a data-visualization palette",
+              "tabular figures; compact",
+              "dashboards, evaluation, admin",
+              "Vercel, Stripe",
+            ],
+          ],
+        },
+      ],
+    },
+  ],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogito.ai/astryx-web",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Mobile-first page archetypes and design guidance for AgentDock web projects",
   "publishConfig": {

package/skills/astryx-web-design/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: astryx-web-design
+description: Use before any UI work in a web-tanstackstart project or a domain package Web. If DESIGN.md is not approved, hold the design-direction discussion with the owner (brand, UI style, UX, color system) and stop until they decide; otherwise create pages only with pnpm page:new and accept them at phone and desktop sizes.
+---
+
+# Astryx web design
+
+| Situation                                                              | Read                                                      |
+| ---------------------------------------------------------------------- | --------------------------------------------------------- |
+| `DESIGN.md` says `status: draft` (new project, or no direction agreed) | `references/design-direction.md`, before any feature work |
+| Adding or changing a page                                              | `references/page-building.md`                             |
+| About to call UI work done                                             | `references/acceptance.md`                                |
+
+Rules that never bend:
+
+- No feature page before the owner approves the design direction. Never choose for the owner, never
+  set a deadline, never fall back to a default.
+- Every page comes from `pnpm page:new`. Never lay a page out from scratch.
+- The shared rules are in `pnpm exec astryx docs dock-design-base`. Read the section you need
+  instead of guessing.
+- Screenshots are for judging what the user sees. Never use them to watch CI or progress.

package/skills/astryx-web-design/references/acceptance.md

@@ -0,0 +1,12 @@
+# Visual acceptance
+
+1. `pnpm dev`, then `pnpm design:samples` for every changed route with the project theme, light and
+   dark, 390x844 and 1440x900.
+2. Open every image and check it against `pnpm exec astryx docs dock-visual-acceptance` and
+   `pnpm exec astryx docs dock-refuse-list`, plus `DESIGN.md`.
+3. Also check: no horizontal scroll at 360px; touch targets at least 44px; keyboard path and visible
+   focus; both locales.
+4. Fix everything you found in one batch and render again. At most two rounds; then report the
+   image folder to the owner.
+
+Screenshots are only for judging the UI. Never use them to watch CI, a pipeline, or progress.

package/skills/astryx-web-design/references/design-direction.md

@@ -0,0 +1,52 @@
+# Design direction (before any feature work)
+
+Outcome: the owner decides the brand, UI style, UX model, and color system. You record them in
+`PRODUCT.md` and `DESIGN.md` and set `DESIGN.md` to `approved`.
+
+## 1 · Understand the product (no visuals yet)
+
+Read the product's intent first (`README.md`; in a domain package also `contract.json` and
+`roadmap.yaml`). Then ask the owner at most three questions per message until `PRODUCT.md` can be
+filled:
+
+- who uses it, where (phone, desktop App, browser), and how often;
+- the one or two core tasks, and what "done" looks like for the user;
+- the brand's personality in three adjectives, and one or two products it must not feel like.
+
+Write `PRODUCT.md`, show it, and correct what the owner corrects.
+
+## 2 · Round 1: three directions
+
+1. Read `pnpm exec astryx docs dock-style-archetypes`. Choose three rows that fit `PRODUCT.md` and
+   differ along one named axis (for example calm ↔ energetic). Never propose a direction that is
+   not in the table.
+2. For each direction write five lines: the archetype and its base theme; type, density, and
+   radius; navigation on phone and on desktop; the first screen; the core task in three steps.
+3. Render the three sample pages (landing, settings, workbench) under each direction's base theme:
+   `pnpm dev`, then
+   `pnpm design:samples --route /zh-CN --route /zh-CN/settings --route /zh-CN/hello --theme <base> --mode light --mode dark --size 390x844 --size 1440x900 --out <dir>/round1/<direction>`.
+   Use the output directory the owner gave you; if none, `design-samples/` at the repository root.
+   If a base theme is not installed yet, add it first with `pnpm exec astryx theme add <slug>`;
+   after the decision, remove the themes that were added only for this round.
+4. Send the owner the five lines and the render folder for each direction. **Stop and wait.** No
+   deadline, no default. If the owner mixes directions or asks for changes, adjust and render again.
+
+## 3 · Round 2: brand color
+
+1. For the chosen direction, generate two or three palette candidates with
+   `pnpm exec astryx theme palette generate <config>` (`pnpm exec astryx docs cli/commands/theme-palette`).
+2. Build each candidate as a theme (`pnpm exec astryx docs author-a-theme`). An ejected theme's
+   local icon file may import packages the app does not have; use the base theme package's exported
+   icon registry instead of adding a dependency. Render the landing page with each candidate, light
+   and dark, phone and desktop, into `<dir>/round2/<candidate>`.
+3. Send the candidates with their contrast ratios for body text. **Stop and wait.**
+
+## 4 · Record
+
+1. Keep the chosen brand theme as the project's default theme; add its built module and CSS to
+   `AppearanceProvider`'s theme options, update its explicit theme-list test, and remove the other
+   candidates.
+2. Fill `DESIGN.md`: front matter, then Overview, Colors, Typography, Layout and navigation, Pages
+   (planned routes with their archetypes), Do and don't.
+3. Add a dated entry to `## Decisions`: what was chosen, what else was shown, and the owner's words.
+4. Set `status: approved`, `approvedBy`, and `approvedAt` only now. Run `pnpm check`.

package/skills/astryx-web-design/references/page-building.md

@@ -0,0 +1,18 @@
+# Building a page
+
+1. Name the page by type and purpose: "<type> page for <purpose>" (types: landing, workbench,
+   list, form, settings, editor). Put the page type last: write `mobile settings page`, not
+   `settings page on mobile`. Run `pnpm page:new "<intent>" --route <path>`. If it rejects the
+   intent, pick a template from the list it prints and pass `--template <id>`.
+2. Replace the `SAMPLE_*` data with feature data through the feature's public API (`LLM.md` §7).
+3. Write the page's copy in `src/i18n/pages/<page>.ts` for every locale.
+4. Change the page only inside its sections; keep its frame, gaps, and padding. For a part the
+   archetype lacks, `pnpm exec astryx build "<part>"` lists blocks; print one with
+   `pnpm exec astryx template <Block>`, then move its strings to the catalog and drop any `style`
+   attribute.
+5. A domain component (a canvas, a player) goes into the archetype's slot; never replace the frame.
+6. Follow `DESIGN.md` and `pnpm exec astryx docs dock-design-base`. Run `pnpm check`, then
+   `references/acceptance.md`.
+
+Never: lay a page out from scratch; use a Core template without `--allow-core`; add a package to
+satisfy a template's import.