@astryxdesign/cli 0.1.6-canary.eb23da7 → 0.1.6-canary.eb549c8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.6-canary.eb23da7",
+  "version": "0.1.6-canary.eb549c8",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -47,10 +47,6 @@
       "types": "./src/types/integration.d.ts",
       "import": "./src/integration.mjs"
     },
-    "./doc": {
-      "types": "./src/types/doc.d.ts",
-      "import": "./src/doc.mjs"
-    },
     "./template": {
       "types": "./src/types/template-api.d.ts",
       "import": "./src/template.mjs"
@@ -79,10 +75,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.eb23da7",
-    "@astryxdesign/core": "0.1.6-canary.eb23da7",
-    "@astryxdesign/lab": "0.1.6-canary.eb23da7",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.eb23da7",
+    "@astryxdesign/charts": "0.1.6-canary.eb549c8",
+    "@astryxdesign/core": "0.1.6-canary.eb549c8",
+    "@astryxdesign/lab": "0.1.6-canary.eb549c8",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.eb549c8",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -100,10 +96,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.eb23da7",
-    "@astryxdesign/core": "0.1.6-canary.eb23da7",
-    "@astryxdesign/lab": "0.1.6-canary.eb23da7",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.eb23da7",
+    "@astryxdesign/charts": "0.1.6-canary.eb549c8",
+    "@astryxdesign/core": "0.1.6-canary.eb549c8",
+    "@astryxdesign/lab": "0.1.6-canary.eb549c8",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.eb549c8",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

package/src/api/validate-integration.mjs

@@ -67,6 +67,11 @@ function error(code, message) {
   return {code, severity: 'error', message};
 }
 
+/** @param {string} code @param {string} message @returns {Issue} */
+function warning(code, message) {
+  return {code, severity: 'warning', message};
+}
+
 /**
  * Verify each declared contribution root exists on disk. A declared-but-missing
  * root is a `missing_root` error.
@@ -360,3 +365,6 @@ export function summarizeIssues(issues) {
   }
   return {errors, warnings};
 }
+
+// Re-export issue constructors for callers/tests that want them.
+export {error as integrationError, warning as integrationWarning};

package/src/lib/component-discovery.mjs

@@ -273,24 +273,14 @@ export function findComponentReadme(coreDir, name) {
  * For "Button" finds src/Button/XDSButton.tsx
  * For "Layout" finds src/Layout/XDSLayout/XDSLayout.tsx
  * For "Card" finds src/Layout/Container/XDSCard.tsx (deep search fallback)
- *
- * Hooks and other functions are authored as `.ts` (e.g. `useMediaQuery.ts`,
- * `useResizable.ts`), so `.ts` candidates are searched alongside `.tsx`. Without
- * this, deriving the import path for a `.ts`-authored function falls back to the
- * bare `@astryxdesign/core` root instead of its tree-shakeable subpath.
  */
 export function findComponentSource(coreDir, name) {
   const srcDir = path.join(coreDir, 'src');
-  // Try the prefixed forms (`XDSButton.tsx`) first since that is the current
-  // on-disk convention, then the bare forms (`Button.tsx`) that the Astryx-prefix
-  // migration (P4) renames to. `.tsx` before `.ts` within each so a component's
-  // `.tsx` wins over a same-named `.ts` helper; `.ts` covers hooks/functions.
-  const candidateFiles = [
-    `XDS${name}.tsx`,
-    `${name}.tsx`,
-    `XDS${name}.ts`,
-    `${name}.ts`,
-  ];
+  // Try the prefixed form (`XDSButton.tsx`) first since that is the current
+  // on-disk convention, then the bare form (`Button.tsx`) that the Astryx-prefix
+  // migration (P4) renames to. Listing the prefixed name first keeps behavior
+  // identical until files are actually renamed.
+  const candidateFiles = [`XDS${name}.tsx`, `${name}.tsx`];
 
   function searchDir(dirPath) {
     if (!fs.existsSync(dirPath)) return null;

package/src/lib/component-loader.mjs

@@ -5,59 +5,6 @@
  */
 
 import {pathToFileURL} from 'node:url';
-import {importUserModule} from './module-loader.mjs';
-import {formatZodError} from './config-schema.mjs';
-import {ComponentDocSchema} from '../doc.mjs';
-
-/**
- * Load a component doc through the shared load/validation boundary.
- *
- * This is the typed counterpart to {@link loadDocs}: it loads `.doc.ts` via
- * jiti (and `.doc.mjs`/`.doc.js` via native import) and validates against
- * {@link ComponentDocSchema}. That schema accepts BOTH formats, so this loader
- * reads whichever the file uses:
- *   - NEW: the factory default export
- *     (`export default createComponentDoc({...})` / `createFunctionDoc` /
- *     `createDoc`) — the same single-export convention
- *     {@link loadModuleWithSchema} uses for config/integration/template. These
- *     carry a stamped `type` and validate against the matching per-kind schema.
- *   - OLD: the legacy loose `export const docs = {...}` (no `type`), validated
- *     against the permissive legacy union.
- * The default export wins when both are present. Throws a readable
- * `formatZodError`-style message on failure. Translations (`docsZh`/
- * `docsDense`) are merged exactly as {@link loadDocs} does so callers see
- * identical output.
- *
- * @param {string} docPath absolute path to a `.doc.{ts,mjs,js}` file
- * @param {{zh?: boolean, dense?: boolean, lang?: string}} [opts]
- * @returns {Promise<object>} the validated (and optionally translated) doc
- */
-export async function loadComponentDoc(
-  docPath,
-  {zh = false, dense = false, lang} = {},
-) {
-  const mod = await importUserModule(docPath);
-  const authored = mod?.default ?? mod?.docs;
-
-  const result = ComponentDocSchema.safeParse(authored);
-  if (!result.success) {
-    throw new Error(formatZodError(docPath, result.error));
-  }
-  const docs = authored;
-
-  const locale = lang || (dense ? 'dense' : zh ? 'zh' : null);
-  if (!locale) return docs;
-
-  const translationKey =
-    locale === 'zh' ? 'docsZh' : locale === 'dense' ? 'docsDense' : null;
-  if (!translationKey || !mod[translationKey]) return docs;
-
-  const translation = mod[translationKey];
-  if (translation.props || translation.components?.some(c => c.props)) {
-    return translation;
-  }
-  return mergeTranslation(docs, translation);
-}
 
 export function mergeTranslation(docs, translation) {
   if (!translation) return docs;

package/src/lib/config-schema.mjs

@@ -73,3 +73,33 @@ export function formatZodError(label, error) {
     .join('; ');
   return `${label} is invalid: ${issues}`;
 }
+
+/**
+ * @param {unknown} config
+ * @returns {import('../types/config').AstryxConfig}
+ */
+export function validateConfig(config) {
+  const result = AstryxConfigSchema.safeParse(config);
+  if (!result.success) {
+    throw new Error(
+      formatZodError('astryx.config default export', result.error),
+    );
+  }
+  return result.data;
+}
+
+/**
+ * @param {unknown} integration
+ * @param {string} [label]
+ * @returns {import('../types/integration').AstryxIntegration}
+ */
+export function validateIntegration(
+  integration,
+  label = 'integration manifest',
+) {
+  const result = AstryxIntegrationSchema.safeParse(integration);
+  if (!result.success) {
+    throw new Error(formatZodError(label, result.error));
+  }
+  return result.data;
+}

package/src/lib/xle/registry.mjs

@@ -230,3 +230,8 @@ export async function buildRegistry({cwd = process.cwd()} = {}) {
   };
   return cachedRegistry;
 }
+
+/** Test seam — drop the module-level cache. */
+export function resetRegistryCache() {
+  cachedRegistry = null;
+}

package/templates/themes/neutral/neutralTheme.ts

@@ -39,19 +39,19 @@ import {neutralIconRegistry} from './icons';
 const neutralSyntax = defineSyntaxTheme({
   name: 'xds-neutral',
   tokens: {
-    keyword: ['#700084', '#efa8ff'], // purple T30/T80
-    string: ['#005600', '#a6d2a2'], // green (sat T30 / pastel T80)
-    comment: ['#737373', '#a3a3a3'], // neutral
-    number: ['#6e3500', '#ffb37f'], // orange
-    function: ['#00458c', '#a0caff'], // blue T30/T80 H=255
-    type: ['#700084', '#efa8ff'], // purple
-    variable: ['#171717', '#e5e5e5'], // near-black / near-white
-    operator: ['#737373', '#a3a3a3'], // neutral
-    constant: ['#6e3500', '#ffb37f'], // orange
-    tag: ['#89001a', '#ffaeaa'], // red
-    attribute: ['#584400', '#eec12f'], // yellow
-    property: ['#005348', '#83dac9'], // teal
-    punctuation: ['#a3a3a3', '#525252'], // neutral
+    keyword: ['#700084', '#efa8ff'],    // purple T30/T80
+    string: ['#005600', '#a6d2a2'],     // green (sat T30 / pastel T80)
+    comment: ['#737373', '#a3a3a3'],    // neutral
+    number: ['#6e3500', '#ffb37f'],     // orange
+    function: ['#00458c', '#a0caff'],   // blue T30/T80 H=255
+    type: ['#700084', '#efa8ff'],       // purple
+    variable: ['#171717', '#e5e5e5'],   // near-black / near-white
+    operator: ['#737373', '#a3a3a3'],   // neutral
+    constant: ['#6e3500', '#ffb37f'],   // orange
+    tag: ['#89001a', '#ffaeaa'],        // red
+    attribute: ['#584400', '#eec12f'],  // yellow
+    property: ['#005348', '#83dac9'],   // teal
+    punctuation: ['#a3a3a3', '#525252'],// neutral
     background: ['#fafafa', '#0a0a0a'],
   },
 });
@@ -127,39 +127,39 @@ export const neutralTheme = defineTheme({
     // All values use the OKLCH Neutral tonal palette (chroma=0).
     // =========================================================================
     '--color-background-surface': ['#ffffff', '#262626'],
-    '--color-background-body': ['#f1f1f1', '#1b1b1b'],
-    '--color-background-card': ['#ffffff', '#1b1b1b'],
+    '--color-background-body':    ['#f1f1f1', '#1b1b1b'],
+    '--color-background-card':    ['#ffffff', '#1b1b1b'],
     '--color-background-popover': ['#ffffff', '#1b1b1b'],
-    '--color-background-muted': ['#f1f1f1', '#1b1b1b'],
+    '--color-background-muted':   ['#f1f1f1', '#1b1b1b'],
 
     // Accent + neutral surface tints (sit alongside backgrounds)
-    '--color-accent': ['#262626', '#ebebeb'],
+    '--color-accent':       ['#262626', '#ebebeb'],
     '--color-accent-muted': ['#f1f1f1', '#262626'],
-    '--color-neutral': ['#0000000F', '#FFFFFF1A'],
+    '--color-neutral':      ['#0000000F', '#FFFFFF1A'],
 
     // Overlays (modal scrims, hover/pressed tints)
-    '--color-overlay': ['#00000080', '#000000CC'],
-    '--color-overlay-hover': ['#0000000D', '#FFFFFF0D'],
+    '--color-overlay':         ['#00000080', '#000000CC'],
+    '--color-overlay-hover':   ['#0000000D', '#FFFFFF0D'],
     '--color-overlay-pressed': ['#0000001A', '#FFFFFF1A'],
 
     // Text
-    '--color-text-primary': ['#171717', '#fafafa'],
+    '--color-text-primary':   ['#171717', '#fafafa'],
     '--color-text-secondary': ['#737373', '#a3a3a3'],
-    '--color-text-disabled': ['#a3a3a3', '#525252'],
-    '--color-text-accent': ['#262626', '#ebebeb'],
-    '--color-on-dark': '#ffffff',
-    '--color-on-light': '#171717',
+    '--color-text-disabled':  ['#a3a3a3', '#525252'],
+    '--color-text-accent':    ['#262626', '#ebebeb'],
+    '--color-on-dark':    '#ffffff',
+    '--color-on-light':   '#171717',
     // Contrast: neutral accent is near-black (L) / near-white (D)
-    '--color-on-accent': ['#ffffff', '#171717'],
+    '--color-on-accent':  ['#ffffff', '#171717'],
     '--color-on-success': ['#ffffff', '#171717'],
-    '--color-on-error': ['#ffffff', '#171717'],
+    '--color-on-error':   ['#ffffff', '#171717'],
     '--color-on-warning': '#171717',
 
     // Icon
-    '--color-icon-accent': ['#262626', '#ebebeb'],
-    '--color-icon-primary': ['#171717', '#fafafa'],
+    '--color-icon-accent':    ['#262626', '#ebebeb'],
+    '--color-icon-primary':   ['#171717', '#fafafa'],
     '--color-icon-secondary': ['#737373', '#a3a3a3'],
-    '--color-icon-disabled': ['#a3a3a3', '#525252'],
+    '--color-icon-disabled':  ['#a3a3a3', '#525252'],
 
     // Status / Sentiment — dark mode follows the issue #2150 rubric:
     //
@@ -372,8 +372,8 @@ export const neutralTheme = defineTheme({
     // =========================================================================
     button: {
       'variant:destructive': {
-        backgroundColor: 'var(--color-error-muted)', // locked pastel red bg
-        color: 'var(--color-error)', // locked T30 red — matches banner/input error text
+        backgroundColor: 'var(--color-error-muted)',  // locked pastel red bg
+        color: 'var(--color-error)',                  // locked T30 red — matches banner/input error text
       },
     },
 
@@ -482,37 +482,6 @@ export const neutralTheme = defineTheme({
       },
     },
 
-    // =========================================================================
-    // StatusDot — fill uses the SAME vivid stops as the filled semantic Badge
-    // (and ProgressBar), so a dot and its badge read as one status language.
-    //
-    // The default component maps each variant to a raw semantic token
-    // (--color-success / --color-error / --color-warning / --color-icon-
-    // secondary), which in light mode are the dark T30/T40 stops meant to
-    // sit as TEXT on a pastel surface — as a solid dot they read muddy
-    // (dark green / maroon / brown). Redirect them to the badge fills.
-    //
-    //   success → badge success bg  (green T45 / dark-ramp T60)
-    //   warning → badge warning bg  (yellow T85, same hex both modes)
-    //   error   → badge error bg    (red T55 / dark-ramp T60)
-    //   accent  → badge info bg     (blue T50 / dark-ramp T60) — the
-    //             StatusDot "accent" is the info/attention color, so it
-    //             pairs with the info badge rather than --color-accent
-    //             (near-black #262626, the darkest offender).
-    //
-    // `neutral` is intentionally NOT overridden: the neutral badge bg is a
-    // near-invisible light gray (--color-background-gray #e5e5e5 / 10% white
-    // wash), fine as a large pill but unreadable as an 8px dot. It keeps the
-    // component default's visible mid-gray (--color-icon-secondary), which is
-    // not among the "too dark" cases.
-    // =========================================================================
-    statusdot: {
-      'variant:success': {backgroundColor: 'light-dark(#198100, #64af4c)'},
-      'variant:warning': {backgroundColor: '#ffce2f'},
-      'variant:error': {backgroundColor: 'light-dark(#e33f4a, #ff705d)'},
-      'variant:accent': {backgroundColor: 'light-dark(#0074e2, #6d9cfe)'},
-    },
-
     // =========================================================================
     // Banner — sits on a hue-tinted surface with colored text/icon:
     //   Light: pastel T90 bg (pulled from --color-{X}-muted / --color-background-blue)

package/docs/internationalization.doc.mjs

@@ -1,243 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../../core/src/docs-types').ReferenceDoc} */
-
-export const docs = {
-  name: 'internationalization',
-  title: 'Internationalization',
-  category: 'guide',
-  description:
-    'Localize astryx component strings, provide translation catalogs, override default text, coexist with your own i18n library, swap languages at runtime, and test translations with the pseudo locale.',
-
-  sections: [
-    {
-      title: 'Quick Start',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set a `locale` — astryx components pick up localized strings automatically.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Wrap your app',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core';
-
-function App() {
-  return (
-    <InternationalizationProvider locale="en">
-      <YourApp />
-    </InternationalizationProvider>
-  );
-}`,
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Read strings inside a component',
-          code: `import {useTranslator} from '@astryxdesign/core';
-
-function SaveButton() {
-  const t = useTranslator();
-  return <button>{t('@myapp.actions.save')}</button>;
-}`,
-        },
-        {
-          type: 'prose',
-          text: 'The hook is available to consumer components too, but using it is entirely optional — many teams keep their app strings on their existing i18n library (react-intl, i18next, next-intl, LinguiJS) and only use `useTranslator` when reading astryx keys. If you do route your own strings through it, we recommend namespacing them (`@myapp.*` or your npm scope) to keep them separated from `@astryx.*`, but this is a convention, not a requirement — the resolver treats every key as an opaque string.',
-        },
-        {
-          type: 'prose',
-          text: "Astryx ships translations only for English today. First-party translations for other locales are on the roadmap and coming soon — track https://github.com/facebook/astryx/issues/3641. In the meantime, if you want astryx UI translated into another locale, you can ship your own catalog through the `messages` prop (covered in the next section). If you're using `useTranslator` for your own strings, you'll want to ship your own catalog either way — astryx only carries the fallback for `@astryx.*` keys, not the ones you author.",
-        },
-      ],
-    },
-    {
-      title: 'Providing locale catalogs',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'Astryx bundles only the English catalog today. To render in any other locale, provide a translation catalog through the `messages` prop and set `locale` accordingly. This matches how MUI, Ant Design, and AG Grid work — the consumer app supplies the catalogs it actually needs so unused translations stay out of the bundle.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Add French',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core';
-import fr from './locales/astryx/fr.json';
-
-<InternationalizationProvider locale="fr" messages={{fr}}>
-  <App />
-</InternationalizationProvider>;`,
-        },
-        {
-          type: 'prose',
-          text: "See `@astryxdesign/core/locales/en.json` for the full inventory of keys to translate. Copy it as the starting point — every key you translate replaces the English default; anything you omit falls back through the locale chain to English (e.g. `pt-BR` walks to `pt` then to shipped `en`), so a partial translation renders as a mix rather than empty text or raw key names.",
-        },
-        {
-          type: 'prose',
-          text: 'A community-maintained set of astryx translations is on the roadmap but not shipped yet. For now, consumer apps that ship in multiple languages own their astryx catalogs alongside their app catalogs. Contributions to a first-party set are welcome — track discussion at https://github.com/facebook/astryx/issues/3641.',
-        },
-      ],
-    },
-    {
-      title: "Overriding astryx's default text",
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'Use `overrides` to change individual strings without shipping a full catalog. Overrides are keyed by locale and merged on top of the built-in and user-supplied catalogs.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Change one string in English',
-          code: `<InternationalizationProvider
-  locale="en"
-  overrides={{en: {'@astryx.pagination.next': 'Next →'}}}
->
-  <App />
-</InternationalizationProvider>`,
-        },
-        {
-          type: 'prose',
-          text: 'Overrides win over both bundled English and any `messages` catalog for the same key. Use them for brand voice tweaks or one-off wording changes.',
-        },
-      ],
-    },
-    {
-      title: 'Using astryx with your own i18n library',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: "Astryx components render astryx strings through astryx's provider. Consumer components render consumer strings through whatever i18n library you already use — react-intl, i18next, next-intl, LinguiJS, and so on. The two systems coexist and read from the same source of truth for the active locale.",
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Astryx + react-intl side by side',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core';
-import {Selector} from '@astryxdesign/core/Selector';
-import {Button} from '@astryxdesign/core/Button';
-import {FormattedMessage, IntlProvider, useIntl} from 'react-intl';
-import astryxFr from './locales/astryx/fr.json'; // astryx's UI, in French
-import appFr from './locales/app/fr.json';       // your app strings, in French
-
-function Pricing() {
-  // Consumer strings — resolved by react-intl.
-  const intl = useIntl();
-
-  return (
-    <section>
-      <h1><FormattedMessage id="pricing.heading" /></h1>
-
-      {/* Astryx Selector — trigger placeholder, search-box placeholder,
-          clear-button aria-label all resolved by
-          <InternationalizationProvider>. Options come from react-intl. */}
-      <Selector
-        label={intl.formatMessage({id: 'pricing.region.label'})}
-        options={[
-          {value: 'na', label: intl.formatMessage({id: 'pricing.region.na'})},
-          {value: 'eu', label: intl.formatMessage({id: 'pricing.region.eu'})},
-        ]}
-        hasSearch
-        hasClear
-      />
-
-      <Button label={intl.formatMessage({id: 'pricing.cta.subscribe'})} />
-    </section>
-  );
-}
-
-export default function App() {
-  return (
-    // Same locale, two providers reading their own catalogs.
-    <IntlProvider locale="fr" messages={appFr}>
-      <InternationalizationProvider locale="fr" messages={{fr: astryxFr}}>
-        <Pricing />
-      </InternationalizationProvider>
-    </IntlProvider>
-  );
-}`,
-        },
-        {
-          type: 'prose',
-          text: 'Keep the two providers in sync on locale, and each library owns its own catalog. Astryx never sees your app strings, and your i18n library never sees astryx internals. Runtime locale swap works the same way — re-render both providers with a new `locale` prop and the whole tree updates live.',
-        },
-        {
-          type: 'prose',
-          text: "Single-catalog usage — where an external i18n runtime like react-intl or i18next resolves both your app strings AND astryx's strings through one provider — is on the roadmap via a `Translator` adapter. Track https://github.com/facebook/astryx/issues/4029. For now, run the two providers side by side as shown above.",
-        },
-      ],
-    },
-    {
-      title: 'Runtime language swap',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'Re-render `<InternationalizationProvider>` with a new `locale` prop and every astryx string updates live. No reload, no separate API call.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Toggle between locales',
-          code: `const [locale, setLocale] = useState<'en' | 'fr'>('en');
-
-<InternationalizationProvider locale={locale} messages={{fr}}>
-  <Button
-    label={locale === 'en' ? 'Français' : 'English'}
-    onClick={() => setLocale(l => (l === 'en' ? 'fr' : 'en'))}
-  />
-  <App />
-</InternationalizationProvider>;`,
-        },
-        {
-          type: 'prose',
-          text: "Persisting the user's choice (localStorage, cookie, URL segment, account setting) is up to the consumer. Astryx reads whatever `locale` you pass in.",
-        },
-      ],
-    },
-    {
-      title: 'Testing your translations',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Switching to it in development instantly reveals any astryx string that isn\'t going through the translator, plus any layout that breaks under longer text.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Turn on pseudo-localization',
-          code: `import pseudo from '@astryxdesign/core/locales/pseudo.json';
-
-<InternationalizationProvider locale="pseudo" messages={{pseudo}}>
-  <App />
-</InternationalizationProvider>;`,
-        },
-        {
-          type: 'prose',
-          text: 'Any bare English text you still see on screen is a hardcoded string that needs to be routed through `useTranslator`.',
-        },
-        {
-          type: 'prose',
-          text: "Pseudoloc also has a subtle caveat worth knowing: the pseudo catalog is complete (astryx generates it from every shipped key), so a component using an astryx-shipped key will always render its pseudo version. Your handwritten translation catalogs, on the other hand, only cover the keys you translated — anything missing falls back to English. That means \"looks perfect in pseudo\" is not the same guarantee as \"looks perfect in French.\" Check each real locale by hand for coverage gaps.",
-        },
-      ],
-    },
-    {
-      title: 'For contributors',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: "Astryx's own strings live in `packages/core/locales/en.json`. New user-facing strings must go through `useTranslator` — this is enforced by the `@astryx/no-hardcoded-i18n-string` ESLint rule. See the AI contribution guide for the alias-and-resolve pattern used when adding new keys.",
-        },
-      ],
-    },
-  ],
-};