chore(core): standardize dev-time console warnings

[cixzhang]

Why

We warn and error to the builder in a bunch of places, but there was no shared pattern. Two problems kept recurring:

1. Warnings fired on every render. A plain if (cond) console.warn(...) in a component body repeats each render, and the "fix" people reached for was extra useState — needless state and re-renders just to gate a log.
2. Inconsistent format. Prefixes were all over the place ([Table], [Astryx], useToast:, bare strings), so it wasn't always obvious which component a message came from.

What

A small dev-logging utility family in @astryxdesign/core, and every existing call site migrated to it:

• useDevWarning(component, message, condition?) — the primary pattern. A ref + useEffect fires the warning once per mount when the condition holds: never during render, never triggering a re-render, no extra state. This is the correct replacement for the render-body/useState anti-pattern.
• devWarn / devError — imperative helpers for the contexts a hook can't reach (plain functions, module init, inside effects). devWarn is dev-only; devError runs in prod too, since it reports real runtime failures that should reach telemetry.
• warnOnce(key, ...) — global once-per-key dedup for singleton warnings (per-theme perf hint, missing i18n key, one-time fallback), replacing three separate ad-hoc Set/boolean flags.

All output is normalized to Component: message.

Risk

Low. Warning text is unchanged in substance — only the prefix is normalized ([Table] → Table:, [Astryx] Theme "x" → Theme: "x", etc.). Warnings are dev-only guardrails; devError preserves the existing always-on behavior for plugin failures. Assertions in the affected tests were updated to match the new prefix.

Testing

• pnpm -F @astryxdesign/core test — 1171 passing (incl. new colocated tests for the util + hook)
• pnpm -F @astryxdesign/lab test src/Drawer — 41 passing
• pnpm -F @astryxdesign/core typecheck, lint, build, and sync-exports --check all clean

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview, Comment	Jul 25, 2026 2:29am

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

Modified Components

Field · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	505	-
Complexity	N/A	High (29)	-

Popover · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	531	-
Complexity	N/A	Very High (51)	-

Table · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	1920	-
Complexity	N/A	Very High (101)	-

Timestamp · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	310	-
Complexity	N/A	Very High (55)	-

Toast · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	716	-
Complexity	N/A	Very High (102)	-

i18n

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	168	-
Complexity	N/A	Low (2)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.7KB	0B

Accessibility Audit

Status: 2 accessibility violation(s) found — 2 serious.

Table - 1 issue(s)

• 🟠 serious: Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds
  • Rule: color-contrast · Affects 4/24 stories · Learn more
  • WCAG: 1.4.3 (Level AA)

Timestamp - 1 issue(s)

• 🟠 serious: Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds
  • Rule: color-contrast · Affects 1/13 stories · Learn more
  • WCAG: 1.4.3 (Level AA)

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}