@ryuenn3123/agentic-senior-core 3.0.48 → 3.0.49

package/.agent-context/prompts/bootstrap-design.md

@@ -56,9 +56,7 @@ If the expressive path needs a new motion, 3D, canvas, scroll, or interaction li
 
 Only downshift ambition after naming the concrete blocker: product fit, content density, measured performance budget, accessibility, device support, package conflict, security risk, or missing runtime capability. A new dependency, package count, or vague performance concern is not a blocker by itself. Pair every downshift with a replacement interaction quality that still changes composition, hierarchy, feedback, or memorability.
 ## Design Flexibility Layer
-`docs/design-intent.json` must separate locked outcomes from flexible expression. The machine contract keeps review invariants stable; it must not freeze exact aesthetic implementation unless repo evidence, accessibility validation, implementation constraints, or explicit user approval locks it.
-
-Record `designFlexibilityPolicy`: lock user goals, runtime constraints, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component-kit theme mapping, signature move implementation, literal anchor artifacts, and spatial metaphors flexible until validated or approved. Semantic roles are required; exact primitives are not automatically locked. Required experience outcomes are separate from candidate implementation moves. Libraries supply behavior, accessibility, primitives, and delivery speed; the project supplies final composition, theme, morphology, and visual language.
+`docs/design-intent.json` must separate locked outcomes from flexible expression. The machine contract keeps review invariants stable; it must not freeze exact aesthetic implementation unless repo evidence, accessibility validation, implementation constraints, or explicit user approval locks it. Record `designFlexibilityPolicy`: lock user goals, runtime constraints, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component-kit theme mapping, signature move implementation, literal anchor artifacts, and spatial metaphors flexible until validated or approved. Semantic roles are required; exact primitives are not automatically locked.
 ## External Inspiration Boundary
 Using outside websites, benchmark apps, galleries, or component examples is useful for constraint discovery, interaction mechanics, and implementation options, but never as a style source to imitate. Extract why a pattern works, then translate it into a current-project rule. Do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture from a reference unless the user explicitly approves that continuity and it passes product fit.
 
@@ -83,16 +81,16 @@ If rich motion or spatial UI is omitted, record the product, content-density, pe
 If 3D or canvas is used, record product role, interaction model, fallback path, runtime/library choice, loading state, keyboard path, and reduced-motion behavior.
 
 ## Token Derivation Audit
-Before implementation, `docs/design-intent.json` must include top-level `derivedTokenLogic`:
-- `anchorReference`
-- `colorDerivationSource`
-- `spacingDerivationSource`
-- `typographyDerivationSource`
-- `motionDerivationSource`
-- `validationRule`
+Before implementation, `docs/design-intent.json` must include top-level `derivedTokenLogic`: `anchorReference`, `colorDerivationSource`, `spacingDerivationSource`, `typographyDerivationSource`, `motionDerivationSource`, `colorSpace`, `spatialBaseUnit`, `typeScaleMethod`, `motionBudget`, and `validationRule`.
 
 Every semantic token role must trace to `anchorReference`. Exact primitive values stay flexible until repo evidence, accessibility validation, implementation constraints, or explicit user approval locks them. If the rationale is "looks good", "common practice", "modern default", or "framework default", derive the token again before UI code.
 
+## Implementation Craft Layer
+Before accepting the design contract, record explicit CSS craft decisions:
+- Color/typography: prefer OKLCH tokens and tinted neutrals for new CSS when supported, preserve existing token formats, name color commitment level, and prefer fluid `clamp()` scales with explicit role contrast, `text-wrap: balance`, and numeric typography decisions.
+- Spatial/motion: name `spatialBaseUnit`, major multiples, optical exceptions, and `motionBudget`; prefer transform/opacity choreography, explicit easing, bounded stagger, and reduced-motion behavior.
+- Implementation anti-attractor: list three default CSS reflexes this task might trigger, reject the most likely one, and choose one distinctive implementation move tied to the product.
+
 ## Library Research Protocol
 If web search is available:
 - Verify each new UI-related library against current official docs.

package/.agent-context/rules/frontend-architecture.md

@@ -19,19 +19,7 @@ Use this rule for UI, UX, page, screen, component, layout, landing, dashboard, f
 
 ## Required Design Contract
 
-Before UI code, create or refine `docs/DESIGN.md` and `docs/design-intent.json`.
-
-The contract must record:
-- `motionPaletteDecision`
-- `designFlexibilityPolicy`
-- `conceptualAnchor`
-- `derivedTokenLogic`
-- `aiSafeUiAudit`
-- `designExecutionPolicy`
-- `designExecutionHandoff`
-- `reviewRubric`
-- `contextHygiene`
-- `libraryResearchStatus` and `libraryDecisions[]`
+Before UI code, create or refine `docs/DESIGN.md` and `docs/design-intent.json`. The contract must record `motionPaletteDecision`, `designFlexibilityPolicy`, `conceptualAnchor`, `derivedTokenLogic`, `aiSafeUiAudit`, `designExecutionPolicy`, `designExecutionHandoff`, `reviewRubric`, `contextHygiene`, `libraryResearchStatus`, and `libraryDecisions[]`.
 
 ## Anti-Generic UI Gate
 
@@ -71,6 +59,7 @@ If the user gives no current-task visual research or reference:
 - Treat motion, 3D, WebGL, canvas, scroll choreography, and animation libraries as first-class options.
 - Omit rich motion or spatial UI only after naming the product-fit reason and the replacement interaction quality.
 - For new screens or broad redesigns, research the expressive implementation path instead of defaulting to static native CSS. Use native or already-installed tools only when they can still deliver the chosen ambition, or when a concrete blocker is documented. Do not downshift because adding a package feels inconvenient; downshift only for a concrete product-fit, accessibility, security, compatibility, device, maintenance, or measured performance reason.
+- Prefer micro-interactions in 150-300ms, layout transitions in 300-500ms, transform/opacity for high-frequency motion, explicit easing, bounded stagger, and reduced-motion alternatives unless evidence changes the budget.
 - Keep reduced-motion, keyboard, loading, performance, mobile, and non-3D fallbacks explicit.
 - Use component kits or headless primitives for behavior and accessibility when they fit. Replace library-default visual language with project-specific composition, tokens, motion, state treatment, and morphology.
 - Keep design-intent flexible: lock user goals, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component skins, candidate signature moves, and external website inspiration flexible until evidence or approval locks them. Convert references into product-fit rules; do not copy layout, palette, component skin, brand posture, or visual metaphor.
@@ -92,6 +81,7 @@ Responsive quality is not scale-only.
 - Tablet must regroup surfaces instead of shrinking desktop.
 - Desktop may expose more context but must not become interchangeable admin chrome.
 - At least one major surface must change position, grouping, priority, or disclosure strategy between mobile and desktop.
+- Prefer container queries, dynamic viewport units, support-checked selectors, subgrid, popover, or disclosure primitives when they simplify recomposition and fallbacks are clear.
 
 ## Accessibility
 
@@ -100,6 +90,12 @@ Responsive quality is not scale-only.
 - Hard checks include focus visibility, focus appearance, target size, keyboard access, accessible authentication, color-only meaning, and dynamic status/state access.
 - Fix accessibility issues without flattening the UI into generic safe chrome unless no expressive safe option remains.
 
+## CSS Production Hardening
+
+- Plan overflow, wrapping, truncation, empty, loading, error, and extreme-content behavior before declaring a layout complete.
+- Prefer `min()`, `max()`, `clamp()`, stable aspect ratios, container-relative sizing, OKLCH, and tinted neutrals for new tokens when supported; preserve existing design-system tokens.
+- Treat recursive card nesting, uniform radius everywhere, shadow on every surface, arbitrary spacing, gray text on saturated color, and library-default skins as drift signals requiring product rationale.
+
 ## Implementation Boundaries
 
 - Follow the shipped project stack and current repo patterns.

package/lib/cli/project-scaffolder/design-contract/validation.mjs

@@ -27,6 +27,10 @@ export function validateDesignContractCompleteness(designIntentContract) {
       'spacingDerivationSource',
       'typographyDerivationSource',
       'motionDerivationSource',
+      'colorSpace',
+      'spatialBaseUnit',
+      'typeScaleMethod',
+      'motionBudget',
       'validationRule',
     ]) {
       if (!hasNonEmptyString(derivedTokenLogic[requiredFieldName])) {

package/lib/cli/project-scaffolder/design-contract.mjs

@@ -334,6 +334,10 @@ function buildDesignIntentContractObject({
       spacingDerivationSource: 'Explain spacing rhythm, density, and exceptions from anchorReference. Spacing grids are layout math, not decorative background lines.',
       typographyDerivationSource: 'Explain display, body, metadata, and data roles from anchorReference.',
       motionDerivationSource: 'Explain duration, easing, choreography, and reduced-motion from anchorReference.',
+      colorSpace: 'Prefer OKLCH for newly generated CSS tokens when supported; preserve existing design-system token formats and document fallback color space.',
+      spatialBaseUnit: 'Name the base spacing unit, major multiples, density exceptions, and optical exceptions before writing spacing values.',
+      typeScaleMethod: 'Prefer fluid clamp() type scales when supported; name ratio, role contrast, balance/wrap behavior, and numeric typography needs.',
+      motionBudget: 'Name micro, layout, entrance, easing, stagger, and reduced-motion budgets; prefer transform/opacity for high-frequency motion.',
       validationRule: 'Every semantic token role must trace to anchorReference; keep exact primitive values flexible unless locked by repo evidence, accessibility validation, implementation constraints, or explicit user approval.',
     },
     motionPaletteDecision: {

package/lib/cli/project-scaffolder/prompt-builders.mjs

@@ -245,10 +245,14 @@ export function buildDesignBootstrapPrompt({
     'Use reduced-motion fallbacks instead of suppressing motion.',
     '',
     '## Token Derivation Audit',
-    'Before implementation, docs/design-intent.json must include derivedTokenLogic.anchorReference plus colorDerivationSource, spacingDerivationSource, typographyDerivationSource, motionDerivationSource, and validationRule.',
+    'Before implementation, docs/design-intent.json must include derivedTokenLogic.anchorReference plus colorDerivationSource, spacingDerivationSource, typographyDerivationSource, motionDerivationSource, colorSpace, spatialBaseUnit, typeScaleMethod, motionBudget, and validationRule.',
     'Every semantic token role must be explainable from anchorReference. If the rationale is only looks good, common practice, modern default, or framework default, derive the token again before UI code.',
     'Keep exact primitive values flexible until repo evidence, accessibility validation, implementation constraints, or explicit user approval locks them.',
     '',
+    '## Implementation Craft Layer',
+    'Record explicit CSS craft decisions before UI code: color space and commitment level, fluid typography method, spacing base unit, motion budget, and the default CSS reflex this project rejects.',
+    'Prefer OKLCH, tinted neutrals, clamp() type scales, transform/opacity motion, and responsive recomposition when supported by the stack; preserve existing design-system tokens and document fallbacks instead of forcing rewrites.',
+    '',
     '## Library Research Protocol',
     'If web search is available, verify every new UI, animation, scroll, 3D, canvas, chart, icon, styling, or primitive library against current official docs and record source URL, fetched date, stable compatible version, purpose, risk, and fallback.',
     'If web search is unavailable or fails, set libraryResearchStatus to pending-verification, record LIBRARY_TO_VERIFY notes, and use native CSS, browser APIs, or already-present project dependencies only when they can preserve the intended ambition until verification is possible.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "3.0.48",
+  "version": "3.0.49",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {

package/scripts/frontend-usability-audit.mjs

@@ -74,9 +74,12 @@ const REQUIRED_FRONTEND_RULE_SNIPPETS = [
   'Prefer visually exploratory, product-derived palettes while preserving WCAG contrast and status clarity.',
   '## Responsive Mutation',
   'Responsive quality is not scale-only.',
+  'container queries',
   '## Accessibility',
   'WCAG 2.2 AA is the hard floor.',
   'APCA is advisory perceptual tuning only.',
+  '## CSS Production Hardening',
+  'overflow, wrapping, truncation',
   '## Implementation Boundaries',
   'Do not hardcode Zustand, React Query, smart/dumb component doctrine',
 ];
@@ -89,6 +92,7 @@ const REQUIRED_BOOTSTRAP_DESIGN_SNIPPETS = [
   'repoEvidence.designEvidenceSummary',
   'research current official docs',
   'Responsive design means recomposition, not resizing.',
+  'Implementation Craft Layer',
   'agent-chosen visual direction',
   'viewport mutation rules',
   'WCAG 2.2 AA is the hard floor',