@ryuenn3123/agentic-senior-core 6.15.1 → 6.16.0

package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/copy-i18n.md

@@ -0,0 +1,103 @@
+# UX Writing, Microcopy & Internationalization (i18n)
+
+UI microcopy is an operational tool, not marketing collateral. Every word on screen either reduces user uncertainty or costs attention.
+
+---
+
+## 1. The 50% Reduction Rule
+
+Draft the copy, then delete half the words without losing meaning. Remove polite throat-clearing, redundant labels, and ornamental adjectives.
+
+| Verbose / Conversational | Direct Operational Copy | Rationale |
+|---|---|---|
+| "In order to get started, please enter your email address below." | "Email address" | Input labels require no preamble. |
+| "Are you sure you want to delete this repository? This action cannot be undone." | "Delete `octocat/hello-world`? This permanently removes all code and history." | Name the exact target and concrete consequence. |
+| "We couldn't seem to find any results matching your search criteria." | "No results for \"billing\"." | State the outcome, mirror the query. |
+| "Successfully updated your preferences." | "Preferences saved." | Past participle, 2 words, passive verb eliminated. |
+| "Click here to view our comprehensive documentation." | "View documentation →" | Never write "click here"; state the destination. |
+
+---
+
+## 2. Action Controls: Verb + Noun Grammar
+
+Buttons and mutation triggers must name their concrete target. Never use ambiguous lone affirmations.
+
+- **Banned:** `Submit`, `OK`, `Yes`, `Proceed`, `Continue`, `Go`, `Done`.
+- **Enforced:** `Create project`, `Invite member`, `Deploy branch`, `Delete webhook`, `Export CSV`.
+
+Exception: Standard multi-step navigation controls in fixed wizards (`Back`, `Next`) where the step indicator supplies the context.
+
+---
+
+## 3. Marketing Buzzword Blacklist
+
+The following words are banned in operational interfaces:
+
+`seamless`, `seamlessly`, `empower`, `empowering`, `robust`, `effortless`, `effortlessly`, `cutting-edge`, `game-changing`, `elevate`, `unlock`, `dive in`, `delightful`, `next-generation`, `supercharge`, `blazing-fast`.
+
+When tempted to write an adjective, state the measurable property instead:
+- Instead of: *"A robust, blazing-fast pipeline."*
+- Write: *"Builds complete in under 45 seconds with isolated caching."*
+
+---
+
+## 4. Single-Language Purity & Anti-Gado-Gado
+
+Interfaces must maintain strict language purity. Mixing two languages within the same surface causes cognitive friction and feels unpolished.
+
+### 4.1 Strict Monolingual Surface
+Choose one language for the entire surface and enforce it across headings, labels, errors, and tooltips:
+- **English UI:** All copy, actions, and timestamps in English.
+- **Indonesian UI:** All copy, actions, and timestamps in standard Indonesian (KBBI/PUEBI).
+
+### 4.2 Ban Hybrid Neologisms (Indonesian Context)
+Never prefix Indonesian grammatical affixes (`di-`, `meng-`, `ter-`, `pe-`) onto raw English stems:
+
+| Hybrid Neologism (Banned) | Standard Indonesian | Pure English Alternative |
+|---|---|---|
+| `di-submit` | `Dikirim` / `Diserahkan` | `Submitted` |
+| `meng-generate` | `Menghasilkan` / `Membuat` | `Generating` |
+| `di-cancel` | `Dibatalkan` | `Cancelled` |
+| `meng-handle` | `Menangani` | `Handling` |
+| `di-approve` | `Disetujui` | `Approved` |
+| `meng-update` | `Memperbarui` | `Updating` |
+| `di-delete` | `Dihapus` | `Deleted` |
+| `me-restore` | `Memulihkan` | `Restoring` |
+
+---
+
+## 5. Dynamic Text Expansion & Internationalization Layout
+
+Text length varies drastically between languages:
+- German and Dutch expand +20% to +35% compared to English.
+- Indonesian expands +15% to +30% for verb-rich phrases.
+- Japanese and Chinese are visually dense and vertically taller.
+
+### 5.1 Layout Rules for Expanding Strings
+1. **Never set fixed widths on action buttons:**
+   ```html
+   <!-- BANNED: clips or overflows in German/Indonesian -->
+   <button class="w-[120px] truncate">Save settings</button>
+
+   <!-- ENFORCED: content-driven width with min-width safety -->
+   <button class="min-w-[5rem] px-4 py-2">Save settings</button>
+   ```
+
+2. **Support multi-line wrapping for headings and table headers:**
+   - Avoid `white-space: nowrap` on containers holding localized strings unless horizontally scrolling is explicitly designed.
+   - Use `hyphens: auto` or flex wrapping on dense metric cards.
+
+3. **Isolate placeholders and interpolated values:**
+   - Never assemble sentences by concatenating translated strings:
+   ```javascript
+   // BANNED: grammar breaks in right-to-left or verb-final languages
+   const msg = t("Deleted") + " " + count + " " + t("items");
+
+   // ENFORCED: parameterized translation tokens
+   const msg = t("deleted_items_count", { count });
+   ```
+
+4. **Numeric and Date Formatting:**
+   - Use `Intl.NumberFormat` and `Intl.DateTimeFormat` with the active locale.
+   - Never hardcode date patterns (`MM/DD/YYYY` fails in locales expecting `DD/MM/YYYY` or `YYYY-MM-DD`).
+

package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/craft/browser-surfaces.md

@@ -0,0 +1,69 @@
+# Craft: Themed Browser Surfaces
+
+Grounded in: Impeccable Browser Surfaces Standard and Web Platform Craft.
+
+> **Why This Matters:** The parts of the viewport you did not author still carry the design. Text selection, input carets, custom scrollbars, and focus rings all ship with unstyled browser defaults that belong to no design system. Theming these surfaces from the project palette is the clearest signal of intentional human craft.
+
+---
+
+## 1. Text Selection Highlight
+
+- **Theme the Selection:**
+  - Standard browser selection (harsh electric blue) frequently clashes with custom brand palettes.
+  - Apply semantic selection tokens matching the brand accent:
+    ```css
+    ::selection {
+      background-color: var(--primary);
+      color: var(--primary-foreground);
+    }
+    ```
+    ```html
+    <!-- Tailwind root or body -->
+    <body class="selection:bg-primary selection:text-primary-foreground">
+    ```
+
+---
+
+## 2. Form Carets & Native Focus
+
+- **Input Caret Color:**
+  - Style the text cursor to match the primary brand token:
+    ```css
+    input, textarea {
+      caret-color: var(--primary);
+    }
+    ```
+- **Consistent Focus Visible:**
+  - Never let the browser default blue outline show on interactive elements:
+    ```css
+    :focus-visible {
+      outline: 2px solid var(--ring);
+      outline-offset: 2px;
+    }
+    ```
+
+---
+
+## 3. Custom Scrollbar Theming
+
+- **Subtle Scrollbars for Overflow Containers:**
+  - Default browser scrollbars on Windows/Linux are bulky and intrusive.
+  - Style internal scroll containers (`overflow-y-auto`, `overflow-x-auto`) with sleek, low-contrast scrollbars:
+    ```css
+    .custom-scrollbar {
+      scrollbar-width: thin;
+      scrollbar-color: var(--border) transparent;
+    }
+    .custom-scrollbar::-webkit-scrollbar {
+      width: 6px;
+      height: 6px;
+    }
+    .custom-scrollbar::-webkit-scrollbar-thumb {
+      background-color: var(--border);
+      border-radius: 9999px;
+    }
+    .custom-scrollbar::-webkit-scrollbar-track {
+      background: transparent;
+    }
+    ```
+

package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/craft/color-surfaces.md

@@ -0,0 +1,46 @@
+# Craft: Color Systems & Surface Elevation
+
+Grounded in: Apple HIG, Google Material Design 3, and Refactoring UI Color Strategies.
+
+---
+
+## 1. Token-First Color Architecture
+
+- **Semantic Tokens Only:**
+  - Every surface, border, and text color must resolve through declared CSS variables or semantic framework tokens:
+    - Backgrounds: `bg-background`, `bg-card`, `bg-muted`, `bg-popover`.
+    - Text: `text-foreground`, `text-muted-foreground`, `text-primary-foreground`.
+    - Borders: `border-border`, `border-input`, `border-primary`.
+  - **Zero Raw Hex Literals in Markup:** Never write inline hex values (`#6366f1`, `#3b82f6`) or arbitrary utility classes (`bg-blue-600`) outside the root token definition.
+
+---
+
+## 2. The 60-30-10 Distribution Rule
+
+- **60% Dominant Neutral Surface:**
+  - The canvas base floor (tinted neutral like slate, zinc, or warm stone—never dead `#000000` or sterile `#ffffff`).
+- **30% Structural Neutral Containers:**
+  - Cards, table backgrounds, navigation headers, sidebars, and divider lines.
+- **10% Purposeful Accent:**
+  - The dedicated brand accent hue.
+  - **Accent Exclusivity:** Accent color is reserved strictly for interactive affordances: Primary CTA button, active navigation indicator, unread dot, selected checkbox.
+  - **Forbidden:** Never use the accent color as background wallpaper, card borders, or decorative section dividers.
+
+---
+
+## 3. Surface Elevation & The "Ghost Card" Ban
+
+- **Stepped Tonal Elevation:**
+  - Build depth through background tone steps rather than heavy drop shadows:
+    - *Base Canvas:* `bg-background` (Level 0)
+    - *Containers & Cards:* `bg-card` (Level 1)
+    - *Recessed Inset Wells (Search bars, secondary filters, code blocks):* `bg-muted/50`
+- **Declare Elevation Once (Ban The Ghost Card):**
+  - Never apply both a distinct 1px border AND a wide, blurry drop shadow to the same container (`border border-slate-200 shadow-lg`). This creates an unnatural "ghost card".
+  - Choose one clear depth language:
+    - *Border-Driven:* Crisp 1px hairline border with alpha (`border-border/60`) and zero or minimal shadow (`shadow-xs`).
+    - *Shadow-Driven:* Floating elevation (`shadow-md`) with borderless or subtle color shift.
+- **Tinted Secondary Text on Colored Surfaces:**
+  - When placing secondary text on a colored or dark surface, tint the text using the parent background hue or foreground token (`text-primary-foreground/70`).
+  - **Never use neutral gray text (`text-slate-400`) on a saturated or colored background.** It produces a muddy, dirty optical illusion.
+

package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/craft/motion.md

@@ -0,0 +1,55 @@
+# Craft: Motion & Micro-Interactions
+
+Grounded in: W3C Motion Specifications, Google Material Motion, and Apple HIG Fluid Interfaces.
+
+---
+
+## 1. The Core Motion Philosophy: "One Authored Moment"
+
+- **Choreography Over Chaos:**
+  - Limit motion to **one authored focal moment** per view (e.g. an interactive slider responding smoothly, or a key metric settling into place).
+  - Never scatter uncoordinated entrance animations across every section. Staggered fade-ins on 10 consecutive cards signal generic AI generation and slow down task execution.
+- **Ease-Out from a Visible Default:**
+  - Content should be visible and readable by default if scripts or animation fail to execute.
+  - Motion must feel natural and physical: fast deceleration / exponential ease-out (`cubic-bezier(0.16, 1, 0.3, 1)`). Avoid linear or cartoonish bouncy transitions.
+
+---
+
+## 2. Technical Performance Floor
+
+- **The Absolute Ban on `transition: all`:**
+  - Never write `transition: all` or `transition-all` in production CSS/Tailwind.
+  - `transition: all` forces the browser engine to recalculate geometry, repaints, and layout costs on every frame whenever any property shifts.
+  - **The Law:** Target only specific, GPU-accelerated compositing properties:
+    ```css
+    /* Good */
+    transition: transform 150ms cubic-bezier(0.16, 1, 0.3, 1), opacity 150ms ease-out;
+    ```
+    ```html
+    <!-- Good Tailwind -->
+    <button class="transition-colors duration-150 active:scale-[0.98]">
+    ```
+- **Never Animate Layout Properties:**
+  - Never animate `width`, `height`, `top`, `left`, `margin`, or `padding`. Animate `transform: scale()` or `transform: translate3d()` instead.
+
+---
+
+## 3. Accessibility & Reduced Motion
+
+- **Mandatory Reduced Motion Fallback:**
+  - Every CSS animation and transition must respect the user's operating system preferences:
+    ```css
+    @media (prefers-reduced-motion: reduce) {
+      *, ::before, ::after {
+        animation-duration: 0.01ms !important;
+        animation-iteration-count: 1 !important;
+        transition-duration: 0.01ms !important;
+        scroll-behavior: auto !important;
+      }
+    }
+    ```
+    ```html
+    <!-- Tailwind -->
+    <div class="transition-transform duration-200 motion-reduce:transition-none">
+    ```
+

package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/craft/typography.md

@@ -0,0 +1,49 @@
+# Craft: Typography & Typesetting
+
+Grounded in: Refactoring UI, Bringhurst's The Elements of Typographic Style, and W3C Type Best Practices.
+
+---
+
+## 1. Font Roles & Typographic Contrast
+
+- **Strict Dual-Role System:**
+  - *Display Role:* Conveys brand character and emotional tone (used for H1, hero headlines, large section markers).
+  - *Body/Functional Role:* Maximizes optical legibility at scale (used for paragraphs, tables, form inputs, button labels, navigation).
+  - Never mix more than two font families on a single screen unless one is a dedicated monospace face for literal code.
+- **Weight Contrast Before Size Inflation:**
+  - Build strong typographic hierarchy by varying font weights (`font-bold` vs `font-normal`) and contrast tokens (`text-foreground` vs `text-muted-foreground`) before jumping to oversized font sizes.
+  - A clean 24px `font-bold` title paired with a 14px `text-muted-foreground` subtitle establishes clearer hierarchy than inflating the title to 48px with identical gray values.
+
+---
+
+## 2. Tracking, Leading & Measure
+
+- **Tracking (Letter-Spacing) Floor:**
+  - Large display headings (> 32px): Tighten tracking slightly (`tracking-tight` / `-0.02em` to `-0.03em`).
+  - **The -0.04em Floor:** Never track tighter than `-0.04em`. Extreme negative tracking collides letterforms and destroys legibility.
+  - Body text (14px–18px): Standard tracking (`tracking-normal` / `0em`). Never tighten body prose.
+  - Uppercase tags/codes: Subtle positive tracking (`tracking-wider` / `+0.05em`).
+- **Leading (Line-Height) Matching:**
+  - Large headings: `leading-tight` (1.1 to 1.25). Loose leading on large display text creates disjointed lines.
+  - Body prose: `leading-relaxed` (1.6 to 1.75). Tight leading on body text causes reading fatigue.
+- **Line Measure Floor:**
+  - Cap continuous reading prose at **65–75 characters per line** (`max-w-prose` / ~680px).
+
+---
+
+## 3. Tabular Numbers & Numeric Craft
+
+- **Tabular Numerals (`tabular-nums`):**
+  - All numbers that change, compare, or align in columns **MUST** carry `tabular-nums` (via CSS `font-variant-numeric: tabular-nums` or Tailwind class `tabular-nums`).
+  - Applies to: prices, balances, data table columns, timers, percentages, and metrics.
+  - *Distinction from font-mono:* Use `tabular-nums` with the standard sans-serif face. Do not force `font-mono` on numbers unless the numbers represent technical addresses, hashes, or code tokens.
+
+---
+
+## 4. The Absolute Ban on Eyebrows & Tracked Heading Kickers
+
+- **Zero Eyebrow Labels:**
+  - Never place a small, uppercase, tracked kicker label above a heading (e.g. `FEATURES`, `WHAT WE DO`, `WHY CHOOSE US`).
+  - An eyebrow is the defining hallmark of generic AI template generation. It adds zero informational value and insults the reader's intelligence.
+  - Let the heading carry its own weight. Delete the kicker entirely.
+

package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/divergence.md

@@ -0,0 +1,127 @@
+# Anti-Convergence & Visual Divergence
+
+Second-order AI design slop occurs when models converge on the same "safe" contemporary aesthetic: dark mode by default, 3 identical rounded cards, purple/indigo gradients, floating pill badges, and generic hero text.
+
+Distinct engineering craft rejects pre-baked template habits in favor of material-derived identity.
+
+---
+
+## 1. The Mirror Test
+
+Before rendering a visual layout, apply the Mirror Test:
+
+> *"Would an adjacent, generic prompt from another user receive this exact combination of layout, typography, and card containers?"*
+
+If the answer is yes:
+1. Break one fundamental structural assumption (e.g., if you naturally reached for a 3-card grid, replace it with a dense comparison table or an asymmetric 70/30 narrative layout).
+2. Shift the focal anchor from generic text to the project's concrete material (a live code terminal, real data payload, interactive simulator, or high-fidelity architecture diagram).
+
+---
+
+## 2. Material-First Architecture
+
+Template-first design forces real content into arbitrary boxes. Material-first design derives the container from the inventory of existing data.
+
+### 2.1 The Material Inventory Protocol
+Inspect what real assets and content actually exist before writing markup:
+- **Available Material:**
+  - Are there real numbers and metrics? $\to$ Display an authentic data table with sorting/filtering.
+  - Is there actual CLI or API interaction? $\to$ Lead with a live syntax-highlighted code block or terminal view.
+  - Are there real product screenshots? $\to$ Full-bleed product stage with zoom/interactive callouts.
+- **Absent Material:**
+  - No customer quotes? $\to$ Zero fake testimonial sliders or generic placeholder personas.
+  - No partner companies? $\to$ Zero generic "Trusted by 10,000+ teams" logo walls.
+  - No enterprise compliance certifications? $\to$ Zero unverified security badges.
+
+---
+
+## 3. Divergence Axes: How to Build Character
+
+When establishing the visual language for a new product, vary decisions along four distinct axes:
+
+```
+                   Axis 1: Layout Posture
+          (Symmetric Grid  ◄──────►  Asymmetric Split / Rail)
+                                │
+   Axis 2: Typographic Voice    │    Axis 3: Surface Tone
+(Technical Monospace / Geometric ◄┼► Editorial Serif / Humanist)
+                                │
+                   Axis 4: Density Scale
+          (Spacious & Airy  ◄──────►  Terminal-Dense Compact)
+```
+
+### 3.1 Layout Posture
+- **Asymmetric Split:** 65% primary visual canvas or working editor, 35% contextual rail or inspector.
+- **Single-Column Narrative:** Focused long-form reading measure with side-margin notes (Tufte style).
+- **Dense Data Stream:** Compact horizontal list rows separated by hairline borders rather than boxed cards.
+
+### 3.2 Typographic Character
+Diverge from the generic "Inter on everything" default by matching font pairing to the product domain:
+- **Developer / Systems Engineering:** Modern neo-grotesque heading + technical monospace code/metrics.
+- **Analytical / Financial / Publishing:** Editorial serif heading (`Newsreader`, `Fraunces`, `Instrument Serif`) paired with crisp sans-serif body (`Geist Sans`, `Plus Jakarta Sans`).
+- **High-Velocity Productivity Tool:** Compact sans-serif with tight tracking and high x-height (`DM Sans`, `General Sans`).
+
+### 3.3 Surface Tone
+- **Warm Editorial:** Cream or paper-tinted backgrounds (`#faf9f6`), deep ink text (`#1c1917`), subtle warm borders.
+- **Technical Monolith:** Deep slate or obsidian canvas (`#090a0f`), cool steel borders (`#1e2230`), crisp laser accents.
+- **High-Key Precision (Clean Light):** Stark white canvas (`#ffffff`), zinc-900 typography, zero shadow elevation (pure 1px border geometry).
+
+---
+
+## 4. Single Signature Element
+
+A memorable, production-grade interface requires exactly **one** standout signature interaction or visual focal point. Attempting to make every button and card special produces visual noise.
+
+Examples of strong signature elements:
+1. **Interactive calculation slider:** Allows prospective users to adjust sliders and immediately see concrete pricing or ROI recalculations.
+2. **Live terminal sandbox:** Interactive terminal tab allowing command execution or simulated payload inspection.
+3. **Master status indicator:** Distinct physical-style LED or pulsing node visualizing live system cluster health.
+4. **Architectural node diagram:** Interactive SVG graph mapping dependencies or data flows.
+
+---
+
+## 5. The Three Waves of AI Tells (Chronological Slop Registry)
+
+Slop is not static. As soon as AI models are instructed to avoid one set of clichés, they converge on the next fashionable alternative.
+
+```
+┌────────────────────────────────────────────────────────┐
+│           THE THREE WAVES OF AI DESIGN TELLS           │
+├────────────────────────────────────────────────────────┤
+│ Wave 1 (2023–2024): The Neon Starter Pack              │
+│ Violet/cyan gradients, glassmorphism, floating drop    │
+│ shadows, 3 identical cards with icon chips, emoji dots.│
+├────────────────────────────────────────────────────────┤
+│ Wave 2 (2025): The Pseudo-Technical Bento              │
+│ Uppercase tracked eyebrows, pill badges ("Beta"),      │
+│ bento card grids, dark canvas with neon ambient halos. │
+├────────────────────────────────────────────────────────┤
+│ Wave 3 (2025–2026): "The Fix That Became the Look"     │
+│ Yellow-cream parchment (#FDFBF7) + terracotta/rust,   │
+│ giant italic serif display, broadsheet newspaper grids,│
+│ performative index numbers (01 / 02), fake coordinates.│
+└────────────────────────────────────────────────────────┘
+```
+
+### 5.1 Defending Against Wave 3 (Editorial Slop)
+The remedy published for Wave 1 and 2 was "warm it up and make it editorial". Models adopted this wholesale, making warm editorial the most instantly recognizable AI tell of 2026:
+- **Terracotta & Cream Monoculture:** Banned as an unprompted AI reflex. Warmth must come from low-chroma stone, authentic product photography, or deep rich ink—not default yellow-cream backgrounds paired with rust orange.
+- **Oversized Italic Serif Cliché:** Do not use italic serif display as a superficial shortcut to "luxury" or "premium" unless the client's actual brand specifically requires it.
+- **Broadsheet Cosplay:** Hairline 1px borders dividing zero-radius dense columns to mimic an 1890s newspaper is an artificial costume. Structure must emerge from clear spatial scale and tonal contrast.
+- **Performative Agency Metadata:** Banned decorative index numbering (`01`, `02`, `(001)`), fake coordinates (`37.77° N`), and version stamps (`©2026 — Scroll`) that convey zero operational data.
+
+---
+
+## 6. Substance Over Restraint (Anti-Sterile Empty Voids)
+
+Stripping away slop ornaments (cards, borders, badges, gradients) is only the first half of design engineering.
+
+> **THE SUBSTANCE INVARIANT:**
+> A page that loses its decorative clutter without gaining substantive weight becomes an uninspired, sterile wireframe. Users and jurors rightly prefer a rich interface with minor tells over an empty, depressing void.
+
+### How to Build Substance Without Slop
+1. **Bold Typographic Scale Disparity:** Set primary headlines with dramatic scale confidence (e.g. `text-5xl` or `text-6xl` bold display paired with tight `leading-[1.1]`, balanced against crisp `text-sm` body).
+2. **Full-Field Color Anchors:** Instead of scattering small floating cards, ground layouts with full-bleed background tone shifts (e.g., transitioning from a clean light canvas into a deep, tinted section floor).
+3. **Authentic Interface Fragments:** For software products, construct working, interactive HTML/CSS UI components (a data table with real rows, an interactive calculation filter, or live code tabs) rather than empty illustrations or placeholder diagrams.
+
+

package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/mobile-responsive.md

@@ -0,0 +1,115 @@
+# Mobile Ergonomics & Responsive Reflow
+
+Mobile interfaces are governed by physical human constraints: thumb reach, screen boundaries, variable virtual keyboards, and shifting viewport chrome.
+
+---
+
+## 1. Viewport Units: The Dynamic Viewport Rule
+
+Mobile browsers dynamically hide and reveal top address bars and bottom navigation chrome during scrolling.
+
+- **Banned:** `height: 100vh` or `h-screen`. Causes bottom controls to hide under the browser navigation bar on iOS Safari and Android Chrome.
+- **Enforced:** `min-height: 100dvh` (dynamic viewport height) or modern fallback cascade:
+
+```css
+.full-screen-container {
+  min-height: 100vh;   /* Fallback for legacy webviews */
+  min-height: 100dvh;  /* Dynamic viewport for modern browsers */
+}
+```
+
+In Tailwind CSS: `min-h-dvh` or `h-dvh`.
+
+---
+
+## 2. Touch Target Geometry: 44px Floor & 8px Clearance
+
+Every interactive element on a touchscreen must provide a physical target large enough for human fingertip variance without accidental trigger of adjacent controls (WCAG 2.5.5 / 2.5.8).
+
+- **Minimum bounding box:** 44 × 44 physical pixels (or CSS pixels at standard DPI).
+- **Minimum clearance:** $\ge 8\text{px}$ between adjacent interactive tap targets.
+
+### Visual Size vs. Hit Target
+If an icon or button must visually appear smaller than 44px (e.g. a 20px close `×` button), expand the tap target via pseudo-elements or padding:
+
+```html
+<!-- Visual size 20px, hit target 44px -->
+<button 
+  type="button" 
+  class="relative p-3 -m-3 inline-flex items-center justify-center text-muted-foreground hover:text-foreground"
+  aria-label="Close dialog"
+>
+  <svg class="w-5 h-5" aria-hidden="true">...</svg>
+</button>
+```
+
+---
+
+## 3. Zero Horizontal Scroll Leaks
+
+Unintended horizontal scrolling destroys mobile ergonomics.
+
+1. **Root Containment:**
+   Set `overflow-x: clip` on the outermost app shell or `body`. Prefer `clip` over `hidden` because `clip` prevents horizontal spill without breaking `position: sticky`.
+
+2. **Contain Preformatted and Table Content:**
+   Never let wide tables or code blocks stretch the page width:
+   ```html
+   <!-- Code block isolation -->
+   <div class="w-full max-w-full overflow-x-auto rounded-md border border-border">
+     <pre class="p-4 text-xs"><code>...</code></pre>
+   </div>
+
+   <!-- Table container isolation -->
+   <div class="w-full max-w-full overflow-x-auto">
+     <table class="w-full min-w-[600px] text-left">...</table>
+   </div>
+   ```
+
+3. **Break Long Strings:**
+   Apply `break-words` or `overflow-wrap: anywhere` on user-generated content, URLs, commit hashes, and file paths.
+
+---
+
+## 4. Mobile Reflow Strategies
+
+Desktop density cannot be shrunk linearly to fit mobile screens; it must be refactored into mobile-native structures.
+
+### 4.1 Dense Table to Stacked Card Reflow
+On screens `< 640px` (`sm:` breakpoint), convert dense multi-column tabular rows into stacked card summaries:
+
+```html
+<!-- Responsive Table Reflow -->
+<div class="block sm:hidden space-y-3">
+  <!-- Mobile Card Representation -->
+  <div class="p-4 rounded-lg border border-border bg-card">
+    <div class="flex items-center justify-between font-medium">
+      <span>INV-2048</span>
+      <span class="text-xs px-2 py-0.5 rounded bg-emerald-500/10 text-emerald-500">Paid</span>
+    </div>
+    <div class="mt-2 text-sm text-muted-foreground flex justify-between">
+      <span>Acme Corp</span>
+      <span class="font-mono tabular-nums text-foreground">$1,200.00</span>
+    </div>
+  </div>
+</div>
+
+<div class="hidden sm:block overflow-x-auto">
+  <table class="w-full">
+    <!-- Desktop Table Representation -->
+  </table>
+</div>
+```
+
+### 4.2 The Thumb Zone & Sticky Action Bars
+Position high-frequency primary actions within natural one-handed thumb sweep:
+- Place primary conversion buttons or form submission bars at the bottom of the viewport on mobile:
+```html
+<div class="sm:static fixed bottom-0 inset-x-0 p-4 bg-background/80 backdrop-blur-md border-t border-border z-20">
+  <button class="w-full py-3 bg-primary text-primary-foreground font-medium rounded-lg">
+    Confirm order ($48.00)
+  </button>
+</div>
+```
+- Account for iOS bottom home indicator safe area using `pb-[env(safe-area-inset-bottom,1rem)]`.
+

package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/modes/experience.md

@@ -0,0 +1,27 @@
+# Surface Mode: Experience (Showcase, Media & Portfolios)
+
+Use for: Creative portfolios, design galleries, interactive product demos, and media showcases.
+
+> **Core Principle:** The visitor is inside the work itself. Interface chrome recedes entirely so the visual artifact, artwork, or interaction leads from the first viewport. The UI serves as a quiet frame for the subject.
+
+---
+
+## 1. Canvas Treatment & Spatial Composition
+
+- **Receding Interface Chrome:**
+  - Navigation headers, footers, and control sidebars should be lightweight, semi-transparent or edge-aligned, maximizing the uninhibited canvas area.
+  - Background surface: Neutral darkroom or gallery tint (`bg-neutral-950` or warm museum white `bg-stone-50`) chosen specifically to elevate the subject's colors without competition.
+- **Full-Bleed Media Presentation:**
+  - Let high-resolution media fill containers naturally with `object-cover` or `object-contain`.
+  - Provide full-screen zoom or modal lightbox views for high-resolution visual inspection.
+
+---
+
+## 2. Interaction & Micro-Choreography
+
+- **Tactile Exploration:**
+  - Interactive previews, drag-to-compare sliders, or spatial hover panning.
+  - Smooth, seamless transitions between overview grid cards and full-fidelity artifact inspection.
+- **Restraint Over Distraction:**
+  - Never add cartoonish particle effects, cursor trails, or autoplaying audio. The craftsmanship of the showcased work is the emotional center.
+

package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/modes/operate.md

@@ -0,0 +1,53 @@
+# Surface Mode: Operate (Productivity & Task Execution)
+
+Use for: Dashboards, data grids, admin consoles, editors, settings, financial ledgers, logistics tools, and developer tools.
+
+> **Core Principle:** The visitor completes a task. Scanability, dense data alignment, low cognitive friction, and native expectations outrank emotional expression. Brand identity lives in the precision of micro-details, not loud decorative containers.
+
+---
+
+## 1. Information Density & Layout Geometry
+
+- **Two-Pane Master-Detail Canvas:**
+  - Fixed-width contextual left rail (240px–280px) for navigation or entity selection.
+  - Fluid, high-density right canvas for inspection, editing, and execution.
+  - Breadcrumb trails with root-to-leaf path (`Projects / Acme / Billing`).
+- **Dense Data Matrix (Tables):**
+  - Table headers must be `sticky top-0` with opaque background and hairline bottom border.
+  - Compact vertical padding: `py-2` to `py-2.5` (row height 36px–40px).
+  - Hover feedback: `hover:bg-muted/40` across the entire row.
+  - Text alignment rule: Left-align text strings, right-align numeric figures and monetary amounts, center status chips and icon actions.
+  - Numeric values must use `tabular-nums` for vertical column alignment.
+- **Progressive Disclosure alih-alih Modal Popups:**
+  - Avoid popping modals for inline edits or sub-entity creation. Use expandable rows, sliding side sheets (drawers), or inline input switches.
+  - Reserve dialogs strictly for destructive confirmations (delete, revoke) or complex isolated workflows (import wizard).
+
+---
+
+## 2. Interactive Controls & Action Semantics
+
+- **Button Heights & Hierarchy:**
+  - Primary button: `h-8` or `h-9` (32px–36px), solid semantic token (`bg-primary text-primary-foreground`).
+  - Secondary button: `h-8` or `h-9`, outline or ghost (`border border-input bg-background hover:bg-muted`).
+  - Icon-only buttons: Strict 1:1 aspect ratio (`h-8 w-8`), padded to meet the 44x44px touch target on touch devices.
+- **Keyboard Affordances:**
+  - Display keyboard shortcuts next to menu items and tooltips (`⌘K`, `Esc`, `↵`).
+  - Full keyboard tabbing through tables and forms without trapped focus.
+- **Inline Filter Bars:**
+  - Place search inputs, filter dropdowns, and date range pickers in a cohesive horizontal toolbar directly above data grids.
+  - Show active filter count chips with single-click dismissal (`Active (3) [×]`).
+
+---
+
+## 3. Status Badges & Telemetry
+
+- **Semantic Indicator Pattern:**
+  - Always pair a color with a text label or icon (never rely on color alone).
+  - Use subtle tinted badge backgrounds with high-contrast text:
+    - Success: `bg-emerald-500/10 text-emerald-700 dark:text-emerald-400`
+    - Warning: `bg-amber-500/10 text-amber-700 dark:text-amber-400`
+    - Danger: `bg-rose-500/10 text-rose-700 dark:text-rose-400`
+    - Neutral/Inactive: `bg-muted text-muted-foreground`
+- **Zero Decorative Halos:**
+  - Never wrap status dots or cards in glowing radial blurs (`shadow-[0_0_12px_#10b981]`). Keep indicators solid and functional.
+