@cogito.ai/astryx-web 0.0.0-stage → 0.2.0

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/docs/dock-touch-mobile.doc.mjs

@@ -0,0 +1,27 @@
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export default {
+  type: 'generic',
+  name: 'dock-touch-mobile',
+  title: 'Dock Touch Mobile',
+  description: 'Touch targets, safe areas, compact navigation, and mobile interaction rules.',
+  sections: [
+    {
+      title: 'Touch and mobile',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Touch targets are at least 44×44px. 32px is allowed only in dense toolbars that never appear on touch screens.',
+            'On compact containers, first-level destinations live in the bottom navigation, and the primary action of a flow sits in a bottom bar within thumb reach.',
+            'Respect safe areas: `viewport-fit=cover` and `env(safe-area-inset-*)` padding on fixed bars.',
+            'Use `100dvh`, not `100vh`.',
+            'Inputs use at least a 16px font so iOS does not zoom.',
+            'Anything revealed on hover must also work by tap; gate hover styles with `@media (hover: hover)`.',
+            'Secondary choices on compact containers open as bottom sheets, not floating menus.',
+          ],
+        },
+      ],
+    },
+  ],
+}

package/docs/dock-visual-acceptance.doc.mjs

@@ -0,0 +1,23 @@
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export default {
+  type: 'generic',
+  name: 'dock-visual-acceptance',
+  title: 'Dock Visual Acceptance',
+  description: 'The render matrix and visual review rules for UI work.',
+  sections: [
+    {
+      title: 'Visual acceptance',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Render the changed pages at 390×844 and 1440×900, in light and dark.',
+            'Check them against A1–A9. Fix everything you find in one batch. At most two rounds, then hand over.',
+            'Screenshots are for judging what the user sees. Never use them to watch CI, pipelines, or progress; read the API.',
+          ],
+        },
+      ],
+    },
+  ],
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@cogito.ai/astryx-web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Mobile-first page archetypes and design guidance for AgentDock web projects",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "astryx-web": "./bin/astryx-web.mjs"
+  },
+  "exports": {
+    "./templates/dock-landing": "./templates/dock-landing.tsx",
+    "./templates/dock-workbench": "./templates/dock-workbench.tsx",
+    "./templates/dock-list": "./templates/dock-list.tsx",
+    "./templates/dock-form-flow": "./templates/dock-form-flow.tsx",
+    "./templates/dock-settings": "./templates/dock-settings.tsx",
+    "./templates/dock-editor-frame": "./templates/dock-editor-frame.tsx"
+  },
+  "files": [
+    "astryx.integration.mjs",
+    "templates/",
+    "docs/",
+    "skills/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "peerDependencies": {
+    "@astryxdesign/cli": ">=0.7.0",
+    "@astryxdesign/core": "^0.7.5"
+  },
+  "peerDependenciesMeta": {
+    "@astryxdesign/cli": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@astryxdesign/cli": "0.7.5",
+    "@astryxdesign/core": "0.7.5",
+    "typescript": "6.0.3"
+  },
+  "scripts": {
+    "check": "pnpm test && pnpm run check:integration && pnpm run check:templates && pnpm run check:intents",
+    "check:integration": "astryx integration check --strict && astryx integration verify",
+    "check:templates": "node scripts/check-templates.mjs",
+    "check:intents": "node scripts/golden-intents.mjs",
+    "check-types": "pnpm run check",
+    "test": "node --test test/*.test.mjs"
+  }
 }

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.

package/templates/dock-editor-frame.doc.mjs

@@ -0,0 +1,19 @@
+/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */
+export default {
+  type: 'page',
+  name: 'Editor frame',
+  displayName: 'Editor frame',
+  description:
+    'A full-bleed editor workspace with a named content slot, floating tools, an overflow menu, and compact bottom navigation.',
+  category: 'Editor - Canvas',
+  keywords: [
+    'canvas editor',
+    'diagram editor',
+    'workspace',
+    'editor frame',
+    'floating toolbar',
+    'mobile',
+  ],
+  replaces: 'canvas-editor',
+  isReady: true,
+}

package/templates/dock-editor-frame.tsx

@@ -0,0 +1,229 @@
+import { DropdownMenu } from '@astryxdesign/core/DropdownMenu'
+import { Icon } from '@astryxdesign/core/Icon'
+import { IconButton } from '@astryxdesign/core/IconButton'
+import { MoreMenu } from '@astryxdesign/core/MoreMenu'
+import { Stack } from '@astryxdesign/core/Stack'
+import { Text } from '@astryxdesign/core/Text'
+import { useTranslator } from '@astryxdesign/core/i18n'
+import * as stylex from '@stylexjs/stylex'
+
+const styles = stylex.create({
+  frame: {
+    position: 'relative',
+    flex: 1,
+    minHeight: 0,
+    width: 'calc(100% + 1.5rem)',
+    marginInline: '-0.75rem',
+    marginBlock: '-0.75rem',
+    overflow: 'hidden',
+    backgroundColor: 'var(--color-background-muted)',
+    '@container (min-width: 420px)': {
+      width: 'calc(100% + 2.5rem)',
+      marginInline: '-1.25rem',
+      marginBlock: '-1.25rem',
+    },
+  },
+  tools: {
+    position: 'absolute',
+    top: 'max(0.75rem, env(safe-area-inset-top))',
+    left: 'max(0.75rem, env(safe-area-inset-left))',
+    zIndex: 2,
+    padding: '0.25rem',
+    borderRadius: 'var(--radius-element)',
+    backgroundColor: 'var(--color-background-card)',
+    boxShadow: 'var(--shadow-med)',
+    '@container (min-width: 640px)': {
+      top: 'max(1.5rem, env(safe-area-inset-top))',
+      left: 'max(1.5rem, env(safe-area-inset-left))',
+    },
+  },
+  menu: {
+    position: 'absolute',
+    top: 'max(0.75rem, env(safe-area-inset-top))',
+    right: 'max(0.75rem, env(safe-area-inset-right))',
+    zIndex: 2,
+    '@container (min-width: 640px)': {
+      top: 'max(1.5rem, env(safe-area-inset-top))',
+      right: 'max(1.5rem, env(safe-area-inset-right))',
+    },
+  },
+  bottomNav: {
+    position: 'absolute',
+    left: '50%',
+    bottom: 'max(0.75rem, env(safe-area-inset-bottom))',
+    transform: 'translateX(-50%)',
+    zIndex: 2,
+    padding: '0.25rem',
+    borderRadius: 'var(--radius-full)',
+    backgroundColor: 'var(--color-background-card)',
+    boxShadow: 'var(--shadow-med)',
+  },
+})
+
+function EditorSlot() {
+  const t = useTranslator()
+
+  return (
+    <Stack
+      aria-label={t('page.__PAGE__.slot.label')}
+      height="100%"
+      hAlign="center"
+      vAlign="center"
+      gap={2}
+    >
+      <Text type="body" weight="semibold">
+        {t('page.__PAGE__.slot.title')}
+      </Text>
+      <Text type="supporting" color="secondary">
+        {t('page.__PAGE__.slot.description')}
+      </Text>
+    </Stack>
+  )
+}
+
+export default function DockEditorFrame() {
+  const t = useTranslator()
+
+  return (
+    <Stack width="100%" xstyle={styles.frame}>
+      <EditorSlot />
+
+      <Stack direction="horizontal" gap={1} xstyle={styles.tools}>
+        <IconButton
+          label={t('page.__PAGE__.tool.select')}
+          icon={<Icon icon="arrowUp" size="sm" />}
+          variant="ghost"
+          size="sm"
+        />
+        <IconButton
+          label={t('page.__PAGE__.tool.move')}
+          icon={<Icon icon="arrowDown" size="sm" />}
+          variant="ghost"
+          size="sm"
+        />
+        <IconButton
+          label={t('page.__PAGE__.tool.find')}
+          icon={<Icon icon="search" size="sm" />}
+          variant="ghost"
+          size="sm"
+        />
+        <IconButton
+          label={t('page.__PAGE__.tool.layers')}
+          icon={<Icon icon="viewColumns" size="sm" />}
+          variant="ghost"
+          size="sm"
+        />
+        <IconButton
+          label={t('page.__PAGE__.tool.adjust')}
+          icon={<Icon icon="wrench" size="sm" />}
+          variant="ghost"
+          size="sm"
+        />
+        <MoreMenu
+          label={t('page.__PAGE__.tool.more')}
+          size="sm"
+          presentation="adaptive"
+          items={[
+            {
+              id: 'duplicate',
+              label: t('page.__PAGE__.action.duplicate'),
+              icon: <Icon icon="copy" size="sm" />,
+            },
+            {
+              id: 'delete',
+              label: t('page.__PAGE__.action.delete'),
+              variant: 'destructive',
+              icon: <Icon icon="close" size="sm" />,
+            },
+          ]}
+        />
+      </Stack>
+
+      <DropdownMenu
+        xstyle={styles.menu}
+        hasChevron={false}
+        button={{
+          label: t('page.__PAGE__.menu'),
+          icon: <Icon icon="menu" size="sm" />,
+          variant: 'secondary',
+          size: 'sm',
+        }}
+        items={[
+          {
+            id: 'rename',
+            label: t('page.__PAGE__.action.rename'),
+          },
+          {
+            id: 'export',
+            label: t('page.__PAGE__.action.export'),
+          },
+        ]}
+      />
+
+      <Stack direction="horizontal" gap={1} xstyle={styles.bottomNav}>
+        <IconButton
+          label={t('page.__PAGE__.nav.back')}
+          icon={<Icon icon="chevronLeft" size="sm" />}
+          variant="ghost"
+          size="sm"
+        />
+        <IconButton
+          label={t('page.__PAGE__.nav.history')}
+          icon={<Icon icon="clock" size="sm" />}
+          variant="ghost"
+          size="sm"
+        />
+        <IconButton
+          label={t('page.__PAGE__.nav.done')}
+          icon={<Icon icon="check" size="sm" />}
+          variant="primary"
+          size="sm"
+        />
+      </Stack>
+    </Stack>
+  )
+}
+
+/*
+astryx-messages
+{
+  "en": {
+    "page.__PAGE__.slot.label": "Editor content",
+    "page.__PAGE__.slot.title": "Editor canvas",
+    "page.__PAGE__.slot.description": "Put the domain editor in this slot.",
+    "page.__PAGE__.tool.select": "Select",
+    "page.__PAGE__.tool.move": "Move",
+    "page.__PAGE__.tool.find": "Find",
+    "page.__PAGE__.tool.layers": "Layers",
+    "page.__PAGE__.tool.adjust": "Adjust",
+    "page.__PAGE__.tool.more": "More tools",
+    "page.__PAGE__.menu": "Editor menu",
+    "page.__PAGE__.action.duplicate": "Duplicate",
+    "page.__PAGE__.action.delete": "Delete",
+    "page.__PAGE__.action.rename": "Rename",
+    "page.__PAGE__.action.export": "Export",
+    "page.__PAGE__.nav.back": "Back",
+    "page.__PAGE__.nav.history": "History",
+    "page.__PAGE__.nav.done": "Done"
+  },
+  "zh-CN": {
+    "page.__PAGE__.slot.label": "编辑器内容",
+    "page.__PAGE__.slot.title": "编辑器画布",
+    "page.__PAGE__.slot.description": "在此插槽中放入领域编辑器。",
+    "page.__PAGE__.tool.select": "选择",
+    "page.__PAGE__.tool.move": "移动",
+    "page.__PAGE__.tool.find": "查找",
+    "page.__PAGE__.tool.layers": "图层",
+    "page.__PAGE__.tool.adjust": "调整",
+    "page.__PAGE__.tool.more": "更多工具",
+    "page.__PAGE__.menu": "编辑器菜单",
+    "page.__PAGE__.action.duplicate": "复制",
+    "page.__PAGE__.action.delete": "删除",
+    "page.__PAGE__.action.rename": "重命名",
+    "page.__PAGE__.action.export": "导出",
+    "page.__PAGE__.nav.back": "返回",
+    "page.__PAGE__.nav.history": "历史",
+    "page.__PAGE__.nav.done": "完成"
+  }
+}
+*/

package/templates/dock-form-flow.doc.mjs

@@ -0,0 +1,19 @@
+/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */
+export default {
+  type: 'page',
+  name: 'Form flow',
+  displayName: 'Form flow',
+  description:
+    'A mobile-first creation form or wizard with one step per screen, inline validation, and actions within thumb reach.',
+  category: 'Form - Flow',
+  keywords: [
+    'creation form',
+    'multi-step form',
+    'wizard form',
+    'mobile form',
+    'mobile',
+    'several steps',
+  ],
+  replaces: 'form-wizard',
+  isReady: true,
+}