SPB Git

Repository Public

DESIGN.md 8.1 KB 138 lines markdown

1# SPNotesDesign — Note Visual System 2.0 « Graphite & Ultramarine · Lumen »23Library product `SPNotesDesign` of the SPNotesCore package (SwiftUI, iOS 18 / macOS 15, no dependency). It is the Swift4side of SPEC §5; the web keeps the same tokens as CSS custom properties. It is **not** re-exported by the `SPNotesCore`5umbrella: `import SPNotesDesign` explicitly. It contains tokens and reusable components only — no app code.67```sh8SPN_ONLY=Design swift test --scratch-path .build-design      # 21 tests, 4 suites9```1011## 1. Colour — `NVColor`1213`NVColor.<token>` is a dynamic `Color` (light / dark follows the view's appearance: `UIColor` dynamic provider on iOS,14`NSColor(name:dynamicProvider:)` on macOS). `NVColor.Token.<token>` gives the raw values (`lightHex`, `darkHex`,15`light` / `dark` as `NVRGB`, `color(for: ColorScheme)` for a fixed colour); `NVColor.Token.all` lists the 18 tokens.1617| token | light | dark | | token | light | dark |18|---|---|---|---|---|---|---|19| bg | #F9FBFD | #0D1016 | | lineStrong | #CCD0D5 | #333640 |20| bgElevated | #FFFFFF | #15181F | | accent | #2F5DDB | #7CA5FF |21| bgSunken | #F0F3F6 | #080A0F | | accentFg | #FBFCFE | #090F1C |22| bgSidebar | #F3F6F9 | #0A0C12 | | accentSoft | #E5F0FF | #1B2A4C |23| bgHover | #EAEDF2 | #1D2028 | | ai | #7E41D2 | #B999FB |24| fg | #151922 | #E8EBEF | | aiSoft | #F3ECFF | #302249 |25| fgMuted | #535862 | #A0A5AE | | success | #008B4E | #5BC083 |26| fgFaint | #848992 | #6A6F77 | | warning | #D98B09 | #F2AF48 |27| line | #E1E4E8 | #22252D | | danger | #CC272E | #F26A64 |2829Rules: ultramarine `accent` is the only interactive hue; violet `ai` marks anything produced by a model (always with30`NVAIBadge`); amber survives only as `warning`. `NVColor.lumen` is the signature gradient accent → ai at 135°31(hero surfaces, capture pulse, graph edges, AI shimmer). `NVRGB` offers `init?(hexString:)` (`#rgb`, `#rrggbb`,32`#rrggbbaa`), `relativeLuminance` and `NVRGB.contrast(_:_:)` (WCAG 2).3334### Measured contrast (WCAG 2 ratio, computed by `ColorTokenTests` from the tokens)3536Text pairs, asserted ≥ 4.5 : 1 in both appearances:3738| pair | light | dark | | pair | light | dark |39|---|---|---|---|---|---|---|40| fg on bg | 16.62 | 15.81 | | accent on bg | 5.82 | 7.61 |41| fg on bgElevated | 17.36 | 14.47 | | accent on bgElevated | 6.08 | 6.96 |42| fg on bgSunken | 15.62 | 16.48 | | accentFg on accent | 5.93 | 7.60 |43| fg on bgSidebar | 16.03 | 16.22 | | accent on accentSoft | 5.25 | 5.53 |44| fg on bgHover | 14.93 | 12.97 | | ai on bg | 5.73 | 7.87 |45| fgMuted on bg | 6.51 | 8.26 | | ai on bgElevated | 5.98 | 7.20 |46| fgMuted on bgElevated | 6.80 | 7.56 | | ai on aiSoft | 5.12 | 5.96 |47| fgMuted on bgSidebar | 6.28 | 8.47 | | fgMuted on bgSunken | 6.12 | 8.61 |4849Below 4.5 — not for body text:5051| pair | light | dark | rule |52|---|---|---|---|53| fgFaint on bg | **3.02** | **4.15** | placeholders, decorative metadata, disabled text only (asserted ≥ 3.0) |54| fgFaint on bgElevated | **3.15** | **3.79** | same |55| success on bg / bgElevated | **4.06** / **4.25** | 9.28 / 8.49 | light: icons, dots, large text; not small text |56| warning on bg / bgElevated | **2.82** / **2.94** | 10.56 / 9.66 | light: fills and icons with a text label in `fg`; never text |57| danger on bg / bgElevated | **4.38** / 4.57 | 7.57 / 6.93 | light: fine on bgElevated, marginal on bg |5859The status values are the specification's and were not altered. Consequence to know: `NVChip` with tone `.success`,60`.warning` or `.danger` writes 11 pt text in the status hue, which is under AA in light mode — pair those chips with an61icon, or use `.neutral` for information that must be read. (Reported to the lead; a darker light-mode status text62token would fix it on both web and native.)6364## 2. Typography — `NVFont`6566| style | size (pt) | weight | design | scales with |67|---|---|---|---|---|68| `micro` | 11 | medium | sans | caption2 |69| `ui` / `uiStrong` | 13 | regular / semibold | sans | footnote |70| `code` | 13 | regular | monospaced | footnote |71| `body` | 16 | regular | sans | body |72| `reading` | 16 (17 on iPhone) | regular | serif | body |73| `h3` / `h2` | 20 / 24 | semibold | serif | title3 / title2 |74| `h1` / `display` | 30 / 40 | bold | serif | title / largeTitle |7576`Text("…").nvFont(.h1)` follows Dynamic Type (`@ScaledMetric` relative to the text style); `NVFont.fixed(.h1)` is the77exact base size. Serif = `Font.Design.serif` (New York). Reading column: `NVSpace.readingMeasure` (680 pt).7879## 3. Spacing, radius, elevation8081`NVSpace`: `xxs 2, xs 4, sm 8, md 12, lg 16, xl 24, xxl 32, xxxl 48, huge 64`.82`NVRadius`: `xs 4, sm 6, md 10, lg 14, xl 20, pill 999`; `NVRadius.shape(_:)` = continuous rounded rectangle.83`NVElevation` through `.nvCard()`, `.nvPop()`, `.nvGlass()` (or `.nvElevation(_:radius:)`):84card = `bgElevated` + hairline + 1 px shadow; pop = shadow offset 16 / blur 40; glass = `.ultraThinMaterial` under a8566 % `bgElevated` surface + hairline, and an opaque surface under Reduce Transparency.8687## 4. Motion — `NVMotion`8889Tokens: `instant` 90 ms, `fast` 160 ms, `base` 240 ms, `slow` 420 ms, `ambient` 900 ms, `exit` (160 ms, exit easing),90`spring` (response 0.38, damping 0.82). Easings `NVMotion.Curve.standard` = cubic-bezier(.2,.8,.2,1),91`.exit` = cubic-bezier(.4,0,1,1).9293**Reduce Motion rule.** Every helper takes it into account; under Reduce Motion an animation is a linear cross-fade of94at most `NVMotion.reducedMaxDuration` (120 ms): no movement, no scale, no spring, no stagger.9596```swift97@Environment(\.accessibilityReduceMotion) private var reduceMotion98withNVAnimation(.base, reduceMotion: reduceMotion) { showPanel.toggle() }99view.nvAnimation(.fast, value: isSelected)                 // reads the environment itself100NVMotion.animation(.spring, reduceMotion: reduceMotion)    // an Animation101```102103Signature motions:104105| # | motion | API | under Reduce Motion |106|---|---|---|---|107| 1 | Living Pages | `.nvBlockReveal(index:)` — rise 6 pt + fade, 18 ms stagger, first 24 blocks only (`NVMotion.staggerDelay`) | fade ≤ 120 ms, no stagger |108| 2 | Morphing Editor | `NVMorphingToolbar(id:) { … }` | cross-fade |109| 3 | Knowledge Connections | `NVEdgeShape` (animatable `progress` trim), `NVEdgeLine(from:to:)` draws itself, Lumen stroke | appears complete, fades in |110| 4 | Fluid Navigation | `.nvSharedTitle(id:in:isSource:)` (matched geometry) | no geometry match, cross-fade |111| 5 | Intelligent Panels | `.nvPanelTransition(edge:)` — slide + blur | cross-fade |112| 6 | Quick Capture | `.nvCaptureScaleIn()` (animate with `.fast`, 160 ms) and `.nvCapturePulse(trigger:)` (Lumen ring) | fade; static ring that fades |113| 7 | Semantic Zoom | `NVSemanticZoom(level:) { level in … }` cross-dissolve; the app owns the scroll anchor | cross-fade ≤ 120 ms |114115`NVTransition.blockReveal / morph / panel(edge:) / captureScaleIn / semanticZoom (reduceMotion:)` give the raw116`AnyTransition`s for custom containers.117118## 5. Components119120| component | use |121|---|---|122| `NVCard { … }` | padded card surface |123| `NVChip("tag", systemImage:, tone:, isSelected:, action:)` | tag, filter, status pill (`NVTone`: neutral, accent, ai, success, warning, danger) |124| `NVSectionHeader("Titre", subtitle:) { accessory }` | section title, header trait |125| `NVEmptyState(systemImage:title:message:actionTitle:action:)` | centred empty state |126| `NVAIBadge(model:style:)` | the mandatory visible marker « Généré par IA » (`.compact` = « IA »; VoiceOver always reads the long form) |127| `NVCitationChip(index:label:action:)` | numbered source of a grounded answer / research citation |128| `NVToolbarGlass { … }` | translucent toolbar chrome |129| `NVProgressDots(count:current:)` / `NVProgressDots()` | determinate steps / indeterminate activity (static under Reduce Motion) |130131Strings are French (source language). Debug builds include a gallery preview (`NVGallery_Previews`, light and dark).132133## 6. Adoption notes for the apps134135- Replace the amber accent (`Palette` on macOS) with `NVColor.accent`; keep amber only through `NVColor.warning`.136- AI output: `NVColor.ai` / `aiSoft` + `NVAIBadge` — never unmarked.137- Do not call `withAnimation` directly for product motion: use `withNVAnimation` / `.nvAnimation` so Reduce Motion is honoured.138
Files main
Menu

Theme