@economic/taco-docs 0.0.1

package/README.md

@@ -0,0 +1,38 @@
+# @economic/taco-docs
+
+Design-system knowledge files for the e-conomic design system — component, foundation, and UI pattern documentation as plain Markdown.
+
+These files are the source-verified "brain" of the design system: structured guidance on how each component, foundation, and pattern should be used, written for humans and AI tools alike. They are not a rendered docs site — they are the content other formats are generated from.
+
+## Install
+
+```sh
+npm install @economic/taco-docs
+```
+
+## Contents
+
+| Folder         | What's in it                                                                                                  |
+| -------------- | ------------------------------------------------------------------------------------------------------------- |
+| `components/`  | Per-component knowledge files (e.g. `toast.md`) — usage guidance, behaviour, accessibility, known limitations |
+| `foundations/` | Design foundations (color, spacing, typography, etc.)                                                         |
+| `patterns/`    | UI patterns — how components combine to solve recurring problems                                              |
+
+Each file follows a consistent schema, leading with usage guidance.
+
+## Usage
+
+The files are Markdown. Read them directly, feed them to an AI tool, or render them however you like. From a Node consumer they resolve under the package root:
+
+```js
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const dir = require.resolve('@economic/taco-docs/package.json').replace(/package\.json$/, '');
+const toast = readFileSync(`${dir}components/toast.md`, 'utf8');
+```
+
+## License
+
+MIT

package/components/toast.md

@@ -0,0 +1,242 @@
+# Toast
+
+## 1. Identity
+
+**Name:** Toast
+**Category:** Feedback & status
+**Status:** available
+**State:** taco
+**Purpose:** Provides non-blocking, temporary feedback about the outcome of a user action.
+**Figma:** Component set "Toast" in Web components library (ZoGBnO9A5jUExnua0wgCIM)
+
+
+---
+
+## 2. When to use
+
+Toasts communicate tone, not urgency. They acknowledge an outcome quietly — the user should be able to keep working without interruption.
+
+**use-when:**
+- Confirming a completed action: "Draft saved", "Invoice sent", "Document uploaded"
+- Providing low-priority system feedback — noticeable but not distracting
+- Reporting a failed action where no user decision is needed: "Export failed"
+- Showing progress on an async operation: "Analysing documents..."
+- Providing an undo opportunity after a reversible action: "Draft deleted" + Undo
+- Feedback does not require a user decision
+
+**do-not-use-when:**
+- The message is critical or blocking — use **Banner** instead
+- The user needs to make a decision before continuing — use **AlertDialog** instead
+- The message needs to persist — use **Banner** instead
+- Detailed error messaging is needed — use **Banner** or **Field** validation instead
+- The feedback is contextual to a specific form field — use inline validation instead
+- The content is promotional
+- Multiple sequential confirmations would fire (e.g. bulk operations) — consolidate into a single toast or use a progress indicator
+
+---
+
+## 3. Design guidance
+
+### Choosing a type
+
+Types communicate tone, not urgency. Choose based on the emotion you want to convey. Success and Information can communicate similar messages, but signal different intent — positive confirmation vs. neutral information. Avoid overusing Error and Warning toasts.
+
+| Type | Purpose | Default duration |
+|---|---|---|
+| Success | Confirms a successful operation | 7500ms |
+| Error | Informs about a failed operation | Persistent |
+| Warning | Highlights a potential issue | Persistent |
+| Information | Neutral system feedback or process activity | Persistent |
+| Loading | Indicates an ongoing process | Persistent |
+| Default | Untyped feedback (no icon) | None — set explicitly |
+
+**Duration reasoning:**
+- **Success (7.5s):** Confirmations are low-stakes — the user triggered the action and the result is expected. Auto-dismissing after 7.5s is safe.
+- **Error / Warning / Information (persistent):** These require the user's attention. Auto-dismissing risks the message disappearing before the user sees it — for example, an invoice booking failure that clears while the user is away from their screen. The user must dismiss explicitly.
+- **Loading (persistent):** Continues until the operation finishes. If an operation takes a long time, consider an async approach with different feedback.
+
+Override the default duration via the `autoClose` option (milliseconds). Omit it or set it to `undefined` for persistent behaviour.
+
+### Content guidelines
+
+- Keep messages brief and action-focused
+- State the outcome, not system mechanics
+- Do not include instructions or next steps
+- Keep it to one message per toast
+- Aim for messages that span no more than 2 lines (max width is 448px). As a rough target, 80–120 characters of English copy fits comfortably
+- Danish translations of English source copy often run 15–30% longer. Where possible, write source copy short enough that the Danish translation still fits in 2 lines
+
+For detailed guidance on formatting and writing system feedback, refer to the content guidelines in `ux-writing.md`.
+
+### Best practices
+
+**Message quality**
+- Do: "Invoice sent", "Document uploaded" — brief, outcome-focused
+- Don't: Long messages explaining what happened and what to do next
+- Don't: Including instructions in a toast
+
+**Toast vs. Dialog**
+- Toasts acknowledge outcomes quietly, without demanding attention or action
+- Do not use toasts while a dialog is open — use error labels, alert banners, or feedback directly tied to the dialog context
+- Do: "Export failed" — simple, low-priority feedback on a user action
+- Don't: Complex errors requiring user decisions — use AlertDialog instead
+
+**Frequency**
+- Consider the frequency of an action when adding a toast trigger
+- If a toast appears so often that users expect it, it is probably the wrong pattern
+- Do: Single "Draft saved" after saving
+- Don't: A toast after every minor system event — too many toasts in sequence are disruptive
+
+**Async operations: show progress, then outcome**
+- For operations that take more than a moment, start with a loading toast, then update it to success or error. This gives users one continuous piece of feedback instead of a spinner disappearing followed by a separate confirmation
+- Do: "Exporting..." → "Export complete" (or "Export failed")
+- Don't: Trigger a loading toast with no message — always describe what is happening
+
+### Actions
+
+- Toasts can include buttons or links to help users respond: "Undo", "View document", "Try again", "Read more"
+- Only the `discrete` button appearance is allowed
+- Maximum one action per toast
+
+Note: buttons and links are currently being redesigned. To avoid technical debt, avoid adding actions to toasts until that work lands.
+
+### Text-id naming
+
+When providing an ID for a toast, use the pattern:
+`TOAST_DOMAIN_SUBDOMAIN_ACTION_OR_STATE_PLURAL_TYPE`
+
+Not all segments are required, but the order should always stay the same.
+
+| Segment | Usage |
+|---|---|
+| TOAST | Starter segment for consistency and searchability |
+| DOMAIN | Identifier for the product area |
+| SUBDOMAIN | Used to specify when there is a clear hierarchy |
+| ACTION_OR_STATE | The action the toast responds to — should reflect the message |
+| PLURAL | Append if a plural version exists |
+| TYPE | Always last. Used if the toast has multiple states. Relates directly to the variant |
+
+Examples:
+- `TOAST_INVOICE_SAVE_SUCCESS`
+- `TOAST_DOCUMENT_UPLOAD_FILE_TOO_BIG_ERROR`
+
+### Anatomy
+
+1. **Badge Icon** — type indicator (tick, close, warning, info) or spinner for loading
+2. **Text** — the message content
+3. **Action** (optional) — a single discrete button or link
+4. **Close button** — always present, dismisses the toast
+5. **Spinner** — replaces badge icon for loading type
+
+---
+
+## 4. Behaviour
+
+### Placement
+Toasts are anchored to the bottom-right corner and overlay page content, except for the top navigation and agreement selector.
+
+### Stacking
+- Multiple toasts stack vertically upward, with the most recent toast at the bottom
+- Be mindful of usage — there is currently no limit to the number of visible toasts, which can cause them to extend beyond the viewport
+
+
+### Duration
+- Users should always be able to dismiss a toast
+- Hovering over a toast pauses its auto-close timer. When the mouse leaves, the timer resumes with the remaining time — it does not restart from the full duration
+- Timer resets to the full duration when toast content is updated (e.g. loading-to-result transition)
+
+### Text overflow
+Toasts have a maximum width of 448px. Text wraps if it exceeds this width.
+
+---
+
+## 5. Accessibility
+
+- Action buttons in toasts (e.g. "Undo", "Try again") must include a clear, descriptive label
+- Toast messages are announced to screen readers when they appear — content should be meaningful when read out of context
+- Toasts do not move focus automatically. Users can continue their current task uninterrupted. Pressing Tab navigates to the toast dismiss button
+- Toast does not trap focus
+
+**Known gaps:**
+- No `Escape` key handler to dismiss toasts
+- Container uses `role="log"` but lacks `aria-live` and `aria-atomic` attributes — screen reader announcement reliability varies by browser
+- Close button touch target size not verified against AAA minimums (44x44 CSS px)
+- No responsive adaptation for narrow viewports
+- Colour contrast ratios not documented for border colours or icon colours against white background
+
+**Open questions for a future replacement:**
+- Should `Escape` dismiss the most recent toast, or all toasts?
+- Is `role="log"` the right ARIA role, or should type determine the role (`role="status"` for success/info, `role="alert"` for error/warning)?
+- What `aria-live` politeness level? `polite` for success/info, `assertive` for error/warning?
+- Should auto-dismiss respect `prefers-reduced-motion`, and should the animation itself fall back to a fade or no animation?
+- Should error toasts be persistent by default rather than 8000ms, given the WCAG 2.2.3 tension?
+- What is the right maximum visible stack count for our context — 1, 3, or some other number?
+
+---
+
+## 6. Known limitations
+
+**No keyboard dismiss.** No `Escape` key handler. Close button is Tab-reachable but there is no shortcut.
+
+**No toast limit.** Rapid-fire operations can stack toasts beyond the viewport. Most established design systems cap visible toasts at 1–3.
+
+**No `prefers-reduced-motion` handling.** The Framer Motion entry/exit animations always play, regardless of the user's system setting. Users who have requested reduced motion still see the spring animation.
+
+**`role="log"` is non-standard for transient notifications.** WAI-ARIA documents `role="log"` for chat-like or feed-like sequences, not for one-off transient messages. Most design systems use `role="status"` (polite) for non-critical and `role="alert"` (assertive) for errors. Our use of `log` is a known divergence — screen reader behaviour may vary.
+
+**Auto-dismiss tension with WCAG 2.2.3.** WAI-ARIA Authoring Practices explicitly discourages auto-dismissing alerts because of WCAG 2.2.3 (sufficient time). We mitigate by pausing the timer on hover and recommending persistent toasts for errors, but this remains an accepted trade-off rather than a resolved issue.
+
+**No built-in action slot.** The product has built a `ToastWithAction` wrapper to render toasts with action buttons in a consistent layout.
+
+**No multi-message / list support.** The product has built a `useFieldlessErrorToast` wrapper to render multiple errors as a list — a recurring need, not supported natively.
+
+**No progress tracking beyond the loading spinner.** Long-running async state needs custom handling (the product has a `usePayFromDocumentsSettingProgressToast` wrapper).
+
+**Fixed positioning only.** Bottom-right via portal. The product has a `setToastPosition` workaround that manipulates container styles to align toasts with specific page elements — evidence the fixed model is insufficient for some layouts.
+
+**No responsive behaviour.** Max width and positioning are hardcoded. No adaptation for narrow viewports.
+
+**All values hardcoded.** No semantic tokens. All colours, spacing, timing, and z-index are Tailwind classes or magic numbers.
+
+**Code defaults differ from guidance.** The API is more permissive than the design intent — see duration table notes.
+
+---
+
+## 7. Do not extend
+
+Toast is a legacy taco component. It is functional and widely adopted, but:
+- All visual values are hardcoded — not on the new token system
+- Accessibility gaps exist (keyboard, focus, ARIA)
+- The fixed positioning model has known workarounds in the product
+
+Use it as-is for current product work. A new DS replacement, if planned, should address the gaps documented here.
+
+---
+
+## 8. Replacement
+
+No replacement is currently planned or in progress.
+
+---
+
+## 9. Related components
+
+**Banner** — Both provide feedback, but Banner is persistent and contextual. Use Banner instead when the message is tied to page state rather than a specific action, needs to persist until the user addresses it, or requires detailed explanation.
+
+**Dialog** — Both can communicate outcomes, but Dialog blocks interaction. Use Dialog instead when the user needs to make a decision before continuing.
+
+**AlertDialog** — Both can communicate problems, but AlertDialog is blocking and confirmatory. Use AlertDialog instead when a destructive or irreversible action needs explicit user confirmation.
+
+---
+
+## 10. Implementation notes
+
+Only what the code can't tell you:
+
+- Toast is imperative and hook-driven — the only component in the design system never rendered as JSX directly
+- Duplicate toasts with identical content are merged, not stacked — the existing toast pulses and its timer resets
+- Updating a toast (e.g. loading to success) removes the original and inserts a new one — this triggers an animation, not an in-place swap
+- Toasts are hidden in print
+- The close button aria-label is localised via the Provider context
+
+For API signatures, props, types, and full technical details: see the component source in the taco repo or `sources/engineering/toast.md`.

package/package.json

@@ -0,0 +1,21 @@
+{
+    "name": "@economic/taco-docs",
+    "version": "0.0.1",
+    "description": "Design-system knowledge files for the e-conomic design system — component, foundation, and UI pattern documentation as Markdown.",
+    "license": "MIT",
+    "keywords": [
+        "design-system",
+        "documentation",
+        "economic",
+        "taco"
+    ],
+    "files": [
+        "components",
+        "foundations",
+        "patterns",
+        "README.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    }
+}