@arbor-education/design-system.components 0.13.0 → 0.14.0

package/.claude/figma-assessment-UKQfcxnT4rlHHNuiumt4o1-11086-97537.md

@@ -1,392 +0,0 @@
-# Figma Design Feasibility Assessment
-## Design: Node 11086:97537 — Take Register (Attendance) Page
-**Written by:** Sophia Petrillo, Componentspert, age none-of-your-business
-**Fact-checked by:** Dorothy Zbornak, QA Expert
-**Date**: 2026-04-10
-
----
-
-## What Is This Thing, Anyway?
-
-Picture it: Sicily, 1928. My mother needed to take the register at the village school. She had twelve bambini, one piece of chalk, and absolutely no component library. And you know what? She built the whole thing from scratch with her bare hands.
-
-TODAY, we have a design system. So let's not build it all from scratch — but we will need to build *some* things.
-
-The "Take Register" page is an attendance marking interface for a school register ("Reception: Form NMC · Tue, 14 Feb 2023, 13:39 (P5)"). It's a full-width 1366px layout with a COLLAPSED left sidebar (only 58px wide — icon-only, no labels), and a main content area showing 12 student rows, each containing a photo, attendance mark toggle buttons, and a mini attendance history panel. The primary interaction is teachers clicking "Present / Absent / Late / Skip" for each student.
-
-Eighteen distinct UI elements. Some are gift-wrapped. Some require building. Let's go.
-
----
-
-## Design Overview
-
-**Register | Desktop 1366px** — Attendance register marking interface for a school class.
-
-### UI Elements Identified
-
-- Top navigation bar (logo, nav links, global search, Ask Arbor AI button, user avatar)
-- Left side navigation — **COLLAPSED/ICON-ONLY variant** (58px wide — different from 232px expanded)
-- Breadcrumbs (Lesson / Lesson Dashboard / Attendance)
-- Back button ("< Back")
-- Page heading H1 "Take Register"
-- Sub-info text row ("Reception: Form NMC · Tue, 14 Feb 2023, 13:39 (P5)")
-- Segmented icon button group — Profile View / List View toggle (270px × 52px pill container)
-- "Mark All Blank As..." primary dropdown button
-- Info/filter row with form label and bulk action
-- Register tiles (12 student rows, each 1268px × 119px) containing:
-  - Student photo avatar (~50px circle)
-  - Student name text
-  - Attendance mark toggle buttons (✕ Absent · ◎ Late · ✓ Present · + Skip)
-  - Today's period summary marks
-  - Attendance history mini-grid (Reg / P1–P5 columns with colored mark indicators)
-  - Optional comment/note text (e.g. "Family Holiday (not agreed)", "Late 178 mins")
-- Separator/dividers between register tile rows
-
----
-
-## Section 1: What We Already Have — Use These As-Is, Don't Reinvent Them
-
-### Back Button (`src/components/button/Button.tsx`)
-
-Simple. Dorothy confirmed `'arrow-left'` exists (line 102 of allowedIcons).
-
-```tsx
-<Button variant="secondary" size="S" iconLeftName="arrow-left">
-  Back
-</Button>
-```
-
----
-
-### Page Heading (`src/components/heading/Heading.tsx`)
-
-One line. No drama.
-
-```tsx
-<Heading level={1}>Take Register</Heading>
-```
-
----
-
-### Sub-info Text Row
-
-Plain HTML with DS typography tokens. No component needed. If "Form NMC" appears in a pill/badge treatment, `<Tag color="neutral" text="Form NMC" />` works.
-
-```tsx
-<p className="ds-register__sub-info">
-  Reception: Form NMC · Tue, 14 Feb 2023, 13:39 (P5)
-</p>
-```
-
----
-
-### "Mark All Blank As..." Dropdown (`src/components/dropdown/Dropdown.tsx`)
-
-`Dropdown` compound + `Button variant="primary"`. Exactly what the component was built for.
-
-```tsx
-<Dropdown>
-  <Dropdown.Trigger asChild>
-    <Button variant="primary" iconRightName="chevron-down">
-      Mark All Blank As...
-    </Button>
-  </Dropdown.Trigger>
-  <Dropdown.Content>
-    <Dropdown.Item onSelect={() => handleMarkAll('present')}>Present</Dropdown.Item>
-    <Dropdown.Item onSelect={() => handleMarkAll('absent')}>Absent</Dropdown.Item>
-    <Dropdown.Item onSelect={() => handleMarkAll('late')}>Late</Dropdown.Item>
-    <Dropdown.Item onSelect={() => handleMarkAll('skip')}>Skip</Dropdown.Item>
-  </Dropdown.Content>
-</Dropdown>
-```
-
----
-
-### Student Photo Avatar (`src/components/avatar/Avatar.tsx`)
-
-Dorothy confirmed `src` works for photos — renders `<img>` with `object-fit: cover`. The three-mode fallback (image → initials → placeholder silhouette) is perfect for a student roster where some kids may not have photos.
-
-**Dorothy-verified sizes:**
-| Size | Pixels |
-|---|---|
-| `'small'` | 20px |
-| `'medium'` | 32px |
-| `'large'` | **48px** ← closest to ~50px |
-| `'extra-large'` | 96px |
-
-```tsx
-<Avatar
-  size="large"
-  src={student.photoUrl}
-  alt={student.name}
-  initials={getInitials(student.name)}
-/>
-```
-
----
-
-### Separators Between Tile Rows (`src/components/separator/Separator.tsx`)
-
-```tsx
-<Separator orientation="horizontal" decorative />
-```
-
----
-
-### Optional Comment / Note Text
-
-Plain `<p>` or `<span>` with DS tokens. If the design shows it styled distinctly (e.g. "Family Holiday (not agreed)" in amber), use `<Tag color="orange" text="Family Holiday (not agreed)" />`.
-
----
-
-### Icon Usage
-
-Dorothy verified all icon names used in this design:
-
-| Design element | Icon name | Verified |
-|---|---|---|
-| Back button | `'arrow-left'` | ✅ line 102 |
-| Profile View toggle button | `'user'` | ✅ line 197 |
-| List View toggle button | `'list'` | ✅ line 157 |
-| Absent mark | `'x'` | ✅ line 198 |
-| Present mark | `'check'` | ✅ line 111 |
-| Skip mark | `'plus'` | ✅ line 175 |
-| Late mark | `'clock-3'` | ✅ line 127 — **`'clock'` DOES NOT EXIST** |
-| Dropdown chevron | `'chevron-down'` | ✅ |
-
----
-
-### UserDropdown + SearchBar (Top Nav)
-
-`UserDropdown variant="dark"` + `SearchBar` — already covered in MIS-69959 (TopNav) and confirmed exported.
-
----
-
-## Section 2: Almost There — Minor Issues or Gotchas
-
-### Segmented Icon Button Group (Profile/List View Toggle)
-
-**What exists:** `Tabs` component has `Tabs.Item` with `iconName` prop and controlled `active` state. Mutual exclusivity can be managed by the caller. Dorothy confirmed `iconName` prop exists on `TabsItem` (line 7).
-
-**What doesn't match:** `Tabs` renders as a tab bar with a **brand-color underline indicator** on the active item. The Figma shows a **pill/capsule container** with the active button having a **filled background** — a segmented control visual, not a tab underline. Fighting Tabs CSS with overrides would be fragile.
-
-**The fix — compose from `Button` primitives:**
-
-```tsx
-const [viewMode, setViewMode] = useState<'profile' | 'list'>('profile');
-
-<div className="ds-register__view-toggle">
-  <Button
-    variant={viewMode === 'profile' ? 'primary' : 'secondary'}
-    iconLeftName="user"
-    iconLeftScreenReaderText="Profile View"
-    onClick={() => setViewMode('profile')}
-    aria-pressed={viewMode === 'profile'}
-  />
-  <Button
-    variant={viewMode === 'list' ? 'primary' : 'secondary'}
-    iconLeftName="list"
-    iconLeftScreenReaderText="List View"
-    onClick={() => setViewMode('list')}
-    aria-pressed={viewMode === 'list'}
-  />
-</div>
-```
-
-With a small SCSS wrapper giving the container `border-radius: var(--border-radius-round)` and no gap between the buttons. **Page-level composition, not a library gap — for this single page.** If this pattern appears on other pages, extract as a `SegmentedControl` library component.
-
-⚠️ **Dorothy's note on Tabs icon-only accessibility:** If you DO use `Tabs.Item` with only `iconName` and no `children`, there is NO `aria-label` automatically applied. You MUST pass one via `tabElementProps={{ 'aria-label': 'Profile View' }}` — the component doesn't handle it for you.
-
----
-
-### Breadcrumbs — Composition Only
-
-Already tracked as **MIS-69957**. Compose from `Button variant="text-link"` + `Separator orientation="vertical"` + semantic `<nav>/<ol>/<li>` HTML.
-
----
-
-## Section 3: Build It From Scratch — These Don't Exist Yet
-
-### AttendanceMarkSelector — HIGHEST PRIORITY FOR THIS PAGE
-
-This is the most important gap on the entire Take Register page. The four-button "✕ Absent · ◎ Late · ✓ Present · + Skip" toggle is the PRIMARY interaction and nothing in the library handles it.
-
-**Why every candidate fails:**
-
-| Candidate | Why it fails |
-|---|---|
-| `RadioButtonInput` / `RadioButtonGroup` | Renders as traditional radio circles. No color-coded active states (red/amber/green), no icon support per option, wrong visual entirely |
-| `Pill` | **Dorothy confirmed: uncontrolled internal state** — there is no `value` or `checked` prop to control it externally after mount. `onclick` fires on MOUNT too (via `useEffect`). Renders as `<span>` with no keyboard accessibility, no `tabIndex`. Cannot reliably deselect a Pill programmatically. |
-| `Tabs` | `role="tab"` is semantically incorrect for data-entry. Tab underline visual is wrong. |
-| Raw `Button` group | Could compose visually, but you'd manually wire mutual exclusivity, color variants, and ARIA — at which point you've built a component anyway. |
-
-**What needs building: `AttendanceMarkSelector`**
-
-```tsx
-// Proposed API
-<AttendanceMarkSelector
-  value="present"            // 'absent' | 'late' | 'present' | 'skip' | null
-  onChange={(value) => {}}   // controlled
-  disabled={false}
-/>
-```
-
-**Requirements:**
-- 4 options: Absent (uses `--color-destructive-*`), Late (uses `--color-caution-*`), Present (uses `--color-success-*`), Skip (uses `--color-grey-*`)
-- Mutually exclusive — semantic `role="radiogroup"` + `role="radio"` per button
-- Each option: icon + text label (`'x'` / `'clock-3'` / `'check'` / `'plus'`)
-- Controlled API — `value` prop drives active state, no internal state
-- `disabled` prop for read-only marks
-- Uses existing semantic color tokens — no new tokens needed
-
-⚠️ **Icon trap:** `'clock'` does NOT exist. Use `'clock-3'` (Dorothy verified, line 127).
-
-**Effort:** Medium. High priority — the page is unusable without it.
-
----
-
-### AttendanceHistoryGrid — Supporting Component
-
-The right-hand panel per register tile showing "Reg P1 P2 P3 P4 P5" column headers with colored mark indicators (green check, red X, amber clock). This is NOT a Table — no sorting, no resize, no AG Grid overhead needed for 6 cells.
-
-**What needs building:** A purely presentational `AttendanceHistoryGrid` component.
-
-```tsx
-// Proposed API
-<AttendanceHistoryGrid
-  periods={[
-    { label: 'Reg', mark: 'present' },
-    { label: 'P1', mark: 'present' },
-    { label: 'P2', mark: 'absent' },
-    { label: 'P3', mark: null },      // unmarked
-    { label: 'P4', mark: 'late' },
-    { label: 'P5', mark: 'present' },
-  ]}
-/>
-```
-
-Internally composes from `Icon` with color overrides using semantic color tokens. CSS grid or flex layout. No AG Grid needed.
-
-**Effort:** Low-Medium. Purely presentational — straightforward to build once `AttendanceMarkSelector` types are defined.
-
----
-
-### RegisterTile — Page-Level Composite (NOT a library component)
-
-The full 1268px × 119px student row composing Avatar + name text + AttendanceMarkSelector + AttendanceHistoryGrid + Separator + optional note. This is too domain-specific for the design system library (it knows about students, attendance marks, period history).
-
-**Build in the MIS app as `RegisterTile.tsx`.** Compose from:
-- `Avatar size="large"` (student photo)
-- Plain text (student name)
-- `AttendanceMarkSelector` (new component above)
-- `AttendanceHistoryGrid` (new component above)
-- `Separator`
-- Conditional `<p>` / `<Tag>` for notes
-
-**Effort:** Low once the two new library components exist.
-
----
-
-### Top Navigation Bar, Side Navigation, Notification Badge, Breadcrumbs (Library Component)
-
-Already tracked: MIS-69959, MIS-69960, MIS-69958, MIS-69957 respectively.
-
-Note: The **collapsed/icon-only variant** of the left nav (58px, icons only) is a different visual state than the 232px expanded variant seen in Student Profile. Whether this is a CSS modifier on the same component or a separate component is a design decision for the SideNavigation build (MIS-69960).
-
----
-
-## Section 4: Tricky Bits — Pay Attention Here
-
-### 1. `'clock'` Does NOT Exist — Use `'clock-3'`
-
-Dorothy caught this. There is NO `'clock'` in allowedIcons. The Late attendance mark icon MUST use `'clock-3'` (line 127, maps to Lucide `Clock3`). TypeScript will catch this at compile time — don't ignore the error.
-
-### 2. Pill Cannot Do Mutually-Exclusive Selection
-
-Dorothy's most important finding for this page: `Pill` is **uncontrolled**. Each pill manages its own `useState`. There's no `value` prop, no `checked` prop, no way to deselect a pill from outside the component. `onclick` fires on mount via `useEffect`. Pill renders as a `<span>` — no keyboard accessibility.
-
-Do NOT use `Pill` for the attendance mark buttons. Build `AttendanceMarkSelector`.
-
-### 3. Icon-Only Buttons/Tabs Need `aria-label` — Not Automatic
-
-Dorothy confirmed: `Tabs.Item` with only `iconName` and no `children` gets no `aria-label` automatically. Pass it via `tabElementProps={{ 'aria-label': 'Profile View' }}`. Same rule applies to icon-only `Button` — always provide `iconLeftScreenReaderText`.
-
-### 4. Avatar Has No 50px Size — Use `'large'` (48px)
-
-No Avatar size hits exactly 50px. `'large'` = 48px is your closest match. Accept it, or apply a `className` override if pixel-perfect is required.
-
-### 5. AttendanceMarkSelector Must Be Controlled
-
-Build it controlled from day one. If you make it uncontrolled (like Pill), the next designer will ask "can we add a Medical mark type?" and you'll have to rewrite it. Controlled API with `value` + `onChange`, token-driven colors per mark type.
-
----
-
-## Section 5: The Verdict
-
-Picture it: Sicily, 1928. My mother took that register with chalk and bare hands. Today, we've got a design system. We've got `Avatar`, `Button`, `Dropdown`, `Separator`, `Heading`, `Icon`. That's your chalk.
-
-What we're MISSING is the actual register form itself — the attendance mark control. That's the desk that isn't there.
-
-### Is It Buildable With Our Existing Components?
-
-**Partially YES. The chrome and structure are covered. The core interaction — `AttendanceMarkSelector` — needs building first.**
-
-### Summary Table
-
-| Design Element | Library Component | Status |
-|---|---|---|
-| Back button | `Button variant="secondary" size="S" iconLeftName="arrow-left"` | ✅ Ready |
-| "Take Register" H1 | `Heading level={1}` | ✅ Ready |
-| Sub-info text | Plain HTML + `Tag` (optional) | ✅ Ready |
-| "Mark All Blank As..." | `Dropdown` + `Button variant="primary"` | ✅ Ready |
-| Student photo avatar | `Avatar size="large"` (48px) | ✅ Ready |
-| Separators between rows | `Separator decorative` | ✅ Ready |
-| Comment/note text | Plain HTML + `Tag` (optional) | ✅ Ready |
-| Icon names (all 8 verified) | `Icon` — 8/8 confirmed (use `'clock-3'` not `'clock'`) | ✅ Ready |
-| UserDropdown / SearchBar (nav) | Already covered | ✅ Ready |
-| Segmented Profile/List toggle | Two `Button`s + custom CSS wrapper | 🔧 Minor composition |
-| Breadcrumbs | Compose: `Button text-link` + `Separator` | 🔧 Per MIS-69957 |
-| Attendance mark buttons (Absent/Late/Present/Skip) | `AttendanceMarkSelector` — does not exist | 🆕 HIGH PRIORITY |
-| Attendance history mini-grid | `AttendanceHistoryGrid` — does not exist | 🆕 New component |
-| RegisterTile container | Page-level `<article>` composite in MIS app | 🆕 App-level |
-| Top navigation bar | MIS-69959 | 🆕 Existing ticket |
-| Left nav (collapsed variant) | MIS-69960 (add collapsed state to ticket) | 🆕 Existing ticket |
-| Notification badge | MIS-69958 | 🆕 Existing ticket |
-| Breadcrumbs library component | MIS-69957 | 🆕 Existing ticket |
-
-### What Actually Needs Work
-
-| Item | Where It Lives | Effort |
-|---|---|---|
-| `AttendanceMarkSelector` | New design system component | Medium |
-| `AttendanceHistoryGrid` | New design system component | Low-Medium |
-| `RegisterTile` | Page-level composite in MIS app | Low (after above) |
-| Segmented toggle (this page) | Page-level composition | Low |
-| Collapsed nav state | Addition to MIS-69960 scope | — |
-
-### Summary Verdict
-
-**9 out of 18 elements** ready with current components. 2 need minor composition. 7 need new work — 4 already have tickets, 2 are new library components, 1 is a page-level composite.
-
-**The critical path:** Build `AttendanceMarkSelector` first — the page literally cannot function without it. `AttendanceHistoryGrid` is display-only and simpler. `RegisterTile` assembles itself once those two exist.
-
-**Recommendation:** The structural chrome (heading, back button, dropdowns, avatar, separators) is all covered. The core domain-specific UI needs two focused new components. Build them — and build them controlled and token-driven from day one.
-
----
-
-## Appendix: Files Referenced in This Assessment
-
-*Every file Dorothy read to verify claims. This assessment is grounded in actual source code.*
-
-- `src/index.ts`
-- `src/components/tabs/Tabs.tsx`
-- `src/components/tabs/TabsItem.tsx`
-- `src/components/pill/Pill.tsx`
-- `src/components/avatar/Avatar.tsx`
-- `src/components/icon/allowedIcons.tsx`
-- `src/components/button/Button.tsx`
-
----
-
-*Analysis by Sophia Petrillo, Componentspert 👜, fact-checked by Dorothy Zbornak 🔍*
-*Powered by Claude Code 🐺*