@astryxdesign/cli 0.6.4-canary.06c8fa3 → 0.6.4-canary.0e1fbdb

package/assets/docs/tree/generate-a-palette.doc.mjs

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes/generate-a-palette`:
+ * turn a few seed colors into a full light and dark color palette.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'generate-a-palette',
+  placement: {parent: 'namespace:themes', slot: 'guides', order: 20},
+  title: 'Generate a palette',
+  category: 'guide',
+  description:
+    'Turn a few seed colors into full light and dark color ramps, saved in the theme folder.',
+  sections: [
+    {
+      id: 'generate-a-palette',
+      title: 'Generate a palette',
+      content: [
+        {
+          type: 'prose',
+          text: 'A theme needs dozens of related colors — shades of each brand color for backgrounds, borders, text, and states, in both light and dark mode. A palette is that full set of shades. Rather than hand-pick every one, you name a few seed colors and generate the rest, so the shades stay consistent and keep enough contrast to read.',
+        },
+        {
+          type: 'prose',
+          text: 'You write a short config naming each color family and its seed, then run `theme palette generate`. It expands each seed into a full light and dark ramp — the scale of shades — and writes the result into the theme folder, where your theme tokens point at it (see {@link generic:define-the-theme}). Keep the config and the generated palette together in that folder.',
+        },
+        {
+          type: 'prose',
+          text: 'The smallest config is one color family: an `id` to name it and a `seed` color to grow it from. Save it as `themes/ocean/palette.config.json`:',
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          code: '{"families": [{"id": "ocean", "seed": "#0074e2"}]}',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: `# Print the palette without writing files
+npx astryx theme palette generate themes/ocean/palette.config.json
+# Write the palette and its receipt
+npx astryx theme palette generate themes/ocean/palette.config.json \\
+  --out themes/ocean/tokens/ocean.palette.ts`,
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: `[ok] Wrote themes/ocean/tokens/ocean.palette.ts
+
+[ok] Wrote themes/ocean/tokens/ocean.palette.receipt.json`,
+        },
+        {
+          type: 'prose',
+          text: 'The command writes two files. `ocean.palette.ts` is the palette your theme tokens will read: it exports `black`, `white`, and `palette` — a ramp of 21 shades (stops `0` to `100`) for both `light` and `dark`. The `.receipt.json` beside it records the exact seeds and settings, so you can regenerate the same palette later. A second run leaves both files alone unless you pass `--overwrite`.',
+        },
+        {
+          type: 'prose',
+          text: 'Add `--preview <file>.html` to also get a web page showing every shade, so you can eyeball the palette in a browser. Write it outside `themes/` so it does not ship in your package. The full list of config fields and options is in {@link command:theme palette generate}.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/grade-template-with-agent.doc.mjs

@@ -0,0 +1,105 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/templates/grade-template-with-agent`:
+ * give an agent the canonical rubric and require a reproducible template grade.
+ */
+
+import {TEMPLATE_RUBRIC} from './template-grading-rubric.doc.mjs';
+
+const scorecardRows = TEMPLATE_RUBRIC.categories
+  .map(({title, max}) => `| ${title} | X | ${max} | |`)
+  .join('\n');
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'grade-template-with-agent',
+  placement: {parent: 'namespace:write-good-templates', slot: 'guides', order: 20},
+  title: 'Grade and improve with an agent',
+  category: 'guide',
+  description:
+    'Give an agent the rubric and evidence it needs to find problems, produce a reproducible scorecard, and improve the template.',
+  sections: [
+    {
+      id: 'give-the-agent-the-rubric',
+      title: 'Give the agent the rubric',
+      content: [
+        {
+          type: 'prose',
+          text: `Grade one exact package revision against template rubric ${TEMPLATE_RUBRIC.version}. Give the agent the template id, the package name, and a clean app that can install the packed package, then use this prompt. Replace every angle-bracket value. The first pass is read-only so the original score and findings stay visible.`,
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          label: 'Agent grading prompt',
+          code: `Grade integration template <id> from <package> at <revision>.
+
+Before scoring:
+1. Read \`npx astryx docs cli/integrations/building-blocks/templates/write-good-templates --full\`.
+2. Read \`npx astryx docs cli/integrations/building-blocks/templates/write-good-templates/template-grading-rubric --full\` and every guide it links.
+3. Inspect the template source, its matching .doc.mjs file, package.json exports and files, and astryx.integration.mjs.
+4. Run \`npx astryx integration verify\` in the package.
+5. Follow \`npx astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/test-template-in-app --full\`: install the packed package in the clean app, copy the template, build the app, and render the behavior matrix.
+
+Score all seven rubric categories. Cite file and line evidence for every deduction. Do not award points for a state you did not inspect. If browser or build evidence is unavailable, say so and mark the template not publishable.
+
+Return the rubric version, package revision, numeric score, letter grade, category scorecard, publishable yes/no verdict, detailed findings, and the top three fixes. Treat 100 as the target. Name every remaining deduction and say whether it is an intentional tradeoff or still needs work. Do not edit files during this first pass.`,
+        },
+      ],
+    },
+    {
+      id: 'require-a-scorecard',
+      title: 'Require a scorecard',
+      content: [
+        {
+          type: 'code',
+          lang: 'markdown',
+          code: `# Template grade: <id>
+
+**Rubric:** ${TEMPLATE_RUBRIC.version}
+**Package revision:** <revision>
+**Type:** page | block
+**Grade:** <letter> (<score>/100)
+**Publishable:** yes | no
+
+| Category | Points | Max | Evidence |
+| --- | ---: | ---: | --- |
+${scorecardRows}
+| **Total** | **X** | **100** | |
+
+## Detailed findings
+- <file:line, rubric rule, observed problem, and deduction>
+
+## Publication blockers
+- <failed pack, copy, build, asset, browser, theme, responsive, or input check>
+
+## Top three fixes
+1. <highest-value fix>
+2. <second fix>
+3. <third fix>`,
+        },
+        {
+          type: 'prose',
+          text: `The category scores must add exactly to the total, and the grade comes from the published bands. The verdict is \`yes\` only when the score is ${TEMPLATE_RUBRIC.minimumScore} or higher and every package, copy, build, asset, and rendered-app check passes.`,
+        },
+      ],
+    },
+    {
+      id: 'improve-and-regrade',
+      title: 'Improve and regrade',
+      content: [
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'Fix publication blockers first.',
+            'Fix every reasonable deduction without hiding it behind helper components or package CSS.',
+            'Pack again, copy into a fresh app, and have the agent repeat the full grade. Keep the earlier scorecard so the improvement is visible.',
+            'Stop only when no reasonable fix remains, and record every intentional tradeoff that still costs points.',
+          ],
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/help.doc.mjs

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @file astryx docs cli/integrations/help — find a CLI message and its fix. */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'help',
+  placement: {parent: 'namespace:integrations', slot: 'guides', order: 40},
+  title: 'Help',
+  summary: 'Find a CLI message and how to fix it.',
+  keywords: ['help', 'troubleshooting', 'error'],
+  slots: {
+    guides: {title: 'Help', accepts: {kinds: ['generic']}},
+  },
+};