11 — Design System Mapping (Bulk Module)
- 1. Token usage (00-shared/02)
- 2. Density & layout rules
- 3. Status colour mapping (module-specific)
- 4. Typography & copy tone
- 5. Motion mapping (00-shared/08)
- 6. Accessibility mapping (00-shared/09)
- 7. Error & empty states (00-shared/03)
- 8. Mapping gaps (flagged for the shared system)
How the bulk module maps onto the shared design system: tokens (00-shared/02), components (00-shared/03, 07), motion (00-shared/08), a11y (00-shared/09), QA baseline (00-shared/10). Material 3 tokens are proposed defaults until a designer finalizes them (00-shared/01 §9).
1. Token usage (00-shared/02)
| Token | Where | Rationale |
|---|---|---|
color.primary (filled) | SS3 Start import, SS1 Next, SS5 Download | single primary action per screen |
color.error | blocking alerts, error rows, failure cards | severity semantics only |
color.warning (amber) | unknown-header chips, size warnings | non-blocking attention |
color.secondaryContainer | optional ColumnChip (rollNumber) | neutral secondary |
color.surfaceVariant | unknown ColumnChip | muted, ignorable |
color.success (M3 extended, 00-shared/02 §4) | all-success summary, stepper checks | status, not CTA |
spacing grid 4/8/12/16/24 | card padding 24, table cell 12, chip gap 8 | consistency |
radius.md (12) | cards, drop zone, tables | forms & data density |
type.titleMedium | screen titles, summary numbers | hierarchy |
type.bodyMedium | table cells; type.labelLarge for row # column | data tables |
2. Density & layout rules
- Data-heavy surfaces (SS2 preview, SS4 errors) use compact density:
12 dp cell padding,
type.bodyMedium, monospace for row numbers (font.family.monoif defined in 00-shared/02, else default). - Wizard cards constrained to ≤ 720 dp (SS1/SS3); tables expand to full width.
- Phone: tables scroll horizontally with the row-# column pinned; summary cards stack.
- Zebra striping off; separation by 1 dp
outlineVariantrow dividers (a11y contrast, 00-shared/09 §3).
3. Status colour mapping (module-specific)
| Status | Colour | Surface |
|---|---|---|
imported count | color.success | ImportSummaryCard |
failed count | color.error | ImportSummaryCard |
| in-flight | color.primary indeterminate bar | ImportProgressPanel |
| duplicate error group | color.warning chip | ErrorGroupChip |
| reference-not-found group | color.primary chip | ErrorGroupChip |
| format / create-time group | color.error chip | ErrorGroupChip |
4. Typography & copy tone
- Numbers (counts, row #) rendered in tabular figures to avoid jitter during count-up (10 §7).
- Copy rules: always pair a number with its meaning ("15 failed", not "15"); error strings displayed verbatim from the server (08 §2); honesty required about sync import (06 §4.1a).
- No emoji in UI strings; icons from the shared set (check, warning, download, upload, table).
5. Motion mapping (00-shared/08)
| Token | Use |
|---|---|
m-fast (120-160 ms) | file accept, error shake, chip state, row expand |
m-base (200-260 ms) | wizard step transition, stepper check, count-up, panel swap |
easing emphasized | transitions; standard for data rows |
6. Accessibility mapping (00-shared/09)
| Requirement | Bulk implementation |
|---|---|
| Live regions | parse failures (SS1), result summary (SS4), contract blocking (SS2) |
| Focus order | drop zone → entity → Next; table cells focusable; CTA Enter |
| Contrast | error/warning text on surface ≥ 4.5:1; chips use containers not outlines |
| Screen-reader labels | tables: real th; stepper: aria-current-equivalent semantics; summary read as one sentence |
| Touch targets | ≥ 48 dp on phone (row actions as tiles, ErrorRowTile) |
| Reduced motion | respect motion.reduced — replace count-up/shake with static states (00-shared/08 §6) |
| Keyboard only | full wizard usable without pointer (10 §8) |
7. Error & empty states (00-shared/03)
| State | Pattern |
|---|---|
| Permission | AppEmptyState + "contact admin" (client gate; server RBAC (planned)) |
| Offline | AppOfflineBanner; import/export blocked (no offline writes, 00-shared/06 §3.5) |
| Rate limited | countdown copy, no auto-retry (00-shared/07 §4) |
| Empty roster export | header-only CSV + toast (06 §5.2) |
| All-failed import | failure card + "fix errors" primary |
8. Mapping gaps (flagged for the shared system)
- No table component in 00-shared/03 —
CSVPreviewTable/ErrorReviewTable(07) become the reference implementation; propose them for the shared library. - No file drop-zone in 00-shared/03 —
FileDropZone(07) is the reference; same forImportStepper. - Material 3 tokens are proposed defaults (00-shared/01 §9) — bulk data tables should be validated against the final token set when it lands.