@deriv-ds/design-intelligence-layer 0.1.0 → 0.3.0

package/guides/brand-voice/deriv-brand-voice.md

@@ -0,0 +1,250 @@
+# Deriv brand voice
+
+A reference guide for anyone writing in Deriv's voice — product copy, marketing, documentation, support, or internal comms. This guide defines how Deriv sounds, not just what it says.
+
+---
+
+## Voice principles
+
+Deriv's voice is **friendly and direct, never condescending**. Every piece of communication — from a button label to a blog post — should feel like it comes from the same company.
+
+These five qualities define the voice:
+
+1. **Capable, not patronising.** Talk to traders as adults who understand risk. Don't over-explain the obvious.
+2. **Warm but efficient.** Be human, then get to the point. "Deposit successful. Funds usually appear in a few minutes." — not "Great news! Your deposit has been successfully processed."
+3. **Calm under pressure.** When something goes wrong — a loss, an error, a delay — the copy should be steady, not alarming. A financial loss is serious. Meet it with composure.
+4. **Personal, not corporate.** Use "you" and "we." The relationship is clear. Avoid the passive voice that hides who does what.
+5. **Simple, always.** Deriv's traders come from 38+ markets. Many are not native English speakers. If a sentence sounds clever, it probably won't translate.
+
+---
+
+## Tone calibration
+
+The voice stays the same. The tone shifts based on what the trader is experiencing.
+
+| Context | Tone | Example |
+|---------|------|---------|
+| Onboarding | Warm, encouraging | "Let's get your account set up. It takes about 3 minutes." |
+| Trade placement | Focused, efficient | "Place trade" — not "Let's go!" |
+| Error or failure | Calm, helpful | "We hit a snag. Try again or contact support." |
+| Financial loss or stop-out | Steady, factual | "Your position has been closed. The market reached your stop-out level." |
+| Success | Confirming, brief | "Withdrawal submitted. We'll process it within 1-3 business days." |
+| Empty state | Inviting, low pressure | "Your trades will appear here. Ready to start?" |
+| Destructive action | Clear, no drama | "Delete your account? This can't be undone." |
+
+---
+
+## Writing rules
+
+### 1. Say the thing first
+
+No preamble. The most important word goes first.
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Please note that your session has expired | Your session has expired |
+| In order to proceed, you'll need to verify your identity | Verify your identity to continue |
+| We wanted to let you know that your deposit was successful | Deposit successful |
+| Kindly be informed that this feature is unavailable | This feature isn't available yet |
+
+### 2. Active voice
+
+Passive voice hides who does what. In Deriv's world, someone always acts.
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Your account has been verified | We've verified your account |
+| An error was encountered | Something went wrong |
+| Your withdrawal has been submitted | We've submitted your withdrawal |
+| Deal cancellation has been activated | Deal cancellation is now active |
+
+### 3. Positive framing
+
+Tell traders what they *can* do, not what they *can't*. This is a hard rule for geographic restrictions.
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Not available in your country | Available in selected countries |
+| You can't withdraw until you verify | Verify your identity to unlock withdrawals |
+| This feature is not supported on mobile | Available on desktop |
+| Stop loss is not available during deal cancellation | Stop loss is available once deal cancellation expires |
+
+### 4. Be specific
+
+Vague copy forces people to guess. Specific copy removes doubt — especially around money.
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| We'll be in touch soon | We'll respond within 2 business days |
+| Your request is being processed | Withdrawal processing — usually 1-3 hours |
+| Please try again later | Try again in a few minutes |
+| A small fee applies | A cancellation fee of [amount] applies |
+
+### 5. Plain language, not jargon
+
+Use Deriv's approved terminology, but write around it plainly. Labels use official terms — everything else explains them in plain language.
+
+| ❌ Jargon | ✅ Plain |
+|-----------|---------|
+| Crystallise your position | Close your trade to lock in your profit or loss |
+| The contract has lapsed | Your trade has expired |
+| Initiate a deposit | Deposit funds |
+| The indicative price is non-deterministic | This price may change before your trade closes |
+
+### 6. One job per string
+
+Each label, message, or instruction does one thing. If copy is trying to explain two things at once, that's a structural problem — don't solve it with longer copy.
+
+---
+
+## Banned words
+
+These are regulatory and brand rules. No exceptions, regardless of channel.
+
+| ❌ Never use | ✅ Use instead | Why |
+|-------------|---------------|-----|
+| invest / investment | trade | Regulatory compliance |
+| investor | trader | Regulatory compliance |
+| win | earn / receive | Regulatory compliance |
+| click here | Descriptive verb + noun (e.g. "Visit the Help centre") | Accessibility and clarity |
+| soon | A specific timeframe (e.g. "within 2 business days") | Precision |
+| a small fee | The actual fee amount | Specificity — always show the number |
+| not available in your country | Available in selected countries | Positive framing — hard rule |
+| something went wrong | Name the specific failure | Too vague — gives people nothing to act on |
+| unsuccessful | Not possible | "Unsuccessful" implies general failure; "not possible" names a constraint |
+
+### On "stake"
+
+Allowed as a UI label and in trade mechanics context. The banned substitution ("initial capital") applies only in regulatory or compliance-facing copy. When in doubt, check with compliance.
+
+---
+
+## Terminology and naming
+
+### Platform names — exact capitalisation
+
+One wrong character damages consistency. These are the only correct forms:
+
+| ✅ Correct | ❌ Never |
+|-----------|---------|
+| Deriv MT5 | dMT5, MT5 alone, Deriv MT 5 |
+| Deriv cTrader | Deriv Ctrader, DCtrader, ctrader |
+| Deriv GO | Deriv Go, DerivGo |
+| Deriv Bot | dBot, DerivBot |
+| Deriv Trader | DTrader, dTrader |
+| SmartTrader | Smart Trader, Smarttrader |
+| Deriv Nakala | Nakala alone |
+| Deriv P2P | DerivP2P, Deriv p2p |
+| Deriv One | Deriv one, DerivOne, D1, Deriv 1 |
+| Swap-free | Swap-Free, SwapFree, Swap free |
+| Zero Spread | Zero spread, zero-spread, ZeroSpread |
+
+### Trade type capitalisation
+
+- Accumulator options (not "Accumulators")
+- Digital options (not "Digitals")
+- Multipliers (capital M as product name)
+- CFDs (never "CFD's")
+- Vanilla options, Lookbacks options — lowercase "options"
+- Rise/Fall, Higher/Lower, Ends Between, Stays Between — as shown
+
+### Derived indices — use the right level
+
+| Term | When to use |
+|------|-------------|
+| Derived indices | Umbrella term for the whole category |
+| Synthetic indices | The simulated subset (Volatility, Crash/Boom, Jump, etc.) |
+| Basket indices | Currency basket products |
+| Derived FX | Simulated forex products |
+
+Never use "Synthetic indices" as a synonym for "Derived indices." They are a subset, not the whole.
+
+---
+
+## Language conventions
+
+### British English — always
+
+| ✅ British | ❌ American |
+|-----------|-----------|
+| authorise | authorize |
+| centre | center |
+| colour | color |
+| programme | program (unless a proper noun) |
+| fulfil | fulfill |
+| licence (noun) | license (noun) |
+| practise (verb) | practice (verb) |
+| realise | realize |
+
+### Sentence case — everywhere
+
+Buttons, headings, labels, navigation, tab names, modal titles — all sentence case. No Title Case except proper nouns and platform/product names.
+
+| ✅ Do | ❌ Don't |
+|-------|----------|
+| Your account settings | Your Account Settings |
+| Deposit funds | Deposit Funds |
+| Trade on Deriv MT5 | Trade On Deriv MT5 |
+
+### Numbers
+
+- Use numerals always: 5%, not "five per cent."
+- Use commas for 4+ digits: 1,200 USD.
+- Truncate large numbers with units only in charts ("1.2K"). Never truncate in financial confirmations — always show the full amount.
+
+---
+
+## Error and loss communication
+
+Errors and loss events are the highest-stakes moments for Deriv's voice. The rules are stricter here.
+
+**Structure for errors:** What happened → What to do → Why (only if it helps).
+
+**Tone rules:**
+- Never blame the user: "You entered an invalid…" → "Enter a valid…"
+- Never use error codes in user-facing messages (logs only).
+- For financial loss events: factual and steady, not apologetic or alarming.
+- Always include what to do next — even if it's just "Try again."
+
+---
+
+## Geographic and regulatory sensitivity
+
+Deriv operates across 38+ markets under different regulatory bodies. Copy must respect this.
+
+| Scenario | Guidance |
+|----------|----------|
+| Feature not available in EU | Do not expose in EU-regulated flows. When in doubt, flag to compliance before writing. |
+| Feature restricted in some non-EU markets | Use positive framing: "Available in selected countries." Never "Not available in your country." |
+| Copy must work across EU and non-EU surfaces | Write for the more restricted version. Flag to the team that a variant may be needed. |
+| Tooltip for an EU-unavailable term in shared codebase | Write the copy, but ensure the component is hidden for EU users. Don't omit the copy — coordinate with engineering. |
+
+---
+
+## Quick reference checklist
+
+Before any copy ships, run through this:
+
+**Clarity**
+- Does it start with the most important word?
+- Can any word be removed without losing meaning?
+- Is the voice active?
+- Is it free of jargon a first-time trader wouldn't know?
+
+**Accuracy**
+- Does it avoid banned words?
+- Are platform and product names capitalised correctly?
+- Is it sentence case?
+- Is it British English?
+- Does it use positive framing for restrictions?
+
+**Action**
+- Does it tell the reader what to do, not just what happened?
+- If it's a button: is the label a verb that matches the outcome?
+- If it's an error: does it say what to do next?
+
+---
+
+## Sources
+
+This guide is derived from Deriv's UX writing system, product glossary, and content style guide. For element-specific rules (character limits, component patterns, copy bricks), refer to the full UX writing skill. For approved product term definitions, refer to the Deriv product glossary.

package/guides/design-system-guide/{trading-game-ds-guide.md → deriv-design-intelligence-guide.md}

@@ -1,7 +1,7 @@
-# Trading Game Design System Guide
+# Deriv Design Intelligence Guide
 
-> **Package:** `@trading-game/design-intelligence-layer`
-> **Audience:** AI agents and developers building UI for the Trading Game. This is the single source of truth for setting up and using the design system in any project.
+> **Package:** `@deriv-ds/design-intelligence-layer`
+> **Audience:** AI agents and developers building UI for Deriv products. This is the single source of truth for setting up and using the design system in any project.
 
 ---
 
@@ -82,7 +82,7 @@ Each component in the catalogue is tagged:
 ### Step 1 — Install the package
 
 ```bash
-npm install @trading-game/design-intelligence-layer@latest --safe-chain-skip-minimum-package-age
+npm install @deriv-ds/design-intelligence-layer@latest --safe-chain-skip-minimum-package-age
 ```
 
 ### Step 2 — Add CSS imports
@@ -92,8 +92,8 @@ In your main CSS file (e.g. `globals.css` or `index.css`):
 ```css
 @import url("https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@300;400;500;600;700;800&display=swap");
 @import "tailwindcss";
-@import "@trading-game/design-intelligence-layer/styles";
-@source "../node_modules/@trading-game/design-intelligence-layer/dist";
+@import "@deriv-ds/design-intelligence-layer/styles";
+@source "../node_modules/@deriv-ds/design-intelligence-layer/dist";
 ```
 
 > **Note:** Fonts are loaded via a direct Google Fonts `@import` URL. Do NOT use `next/font`.
@@ -105,7 +105,7 @@ The design system is light-first. No extra class is required on `<html>` for the
 ### Step 4 — Import components
 
 ```tsx
-import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
+import { Button, Card, Badge } from "@deriv-ds/design-intelligence-layer"
 ```
 
 ---
@@ -457,7 +457,7 @@ All buttons: `font-display font-bold`, sentence case (no `uppercase`, no `tracki
 
 ## 8 — Available Components
 
-> **All components below are exported from `@trading-game/design-intelligence-layer`.**
+> **All components below are exported from `@deriv-ds/design-intelligence-layer`.**
 > - If a component is listed → import and use it. Do NOT re-implement.
 > - If NOT listed → STOP and ask the user (see Rule 1).
 > - For props, variants, sizes, and sub-components → inspect the package's TypeScript types after installation.
@@ -467,13 +467,13 @@ All buttons: `font-display font-bold`, sentence case (no `uppercase`, no `tracki
 All components use the same import path:
 
 ```tsx
-import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
+import { Button, Card, Badge } from "@deriv-ds/design-intelligence-layer"
 ```
 
 ### Example — composed component with sub-components
 
 ```tsx
-import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose } from "@trading-game/design-intelligence-layer"
+import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose } from "@deriv-ds/design-intelligence-layer"
 
 <Dialog>
   <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
@@ -528,7 +528,7 @@ import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, Dialog
 | Kbd | [simple] | KbdGroup |
 | Label | [simple] | — |
 | Link | [simple] | — |
-| Menubar | [complex] | MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem, MenubarSeparator, MenubarLabel, MenubarCheckboxItem, MenubarRadioGroup, MenubarRadioItem, MenubarSub, MenubarSubTrigger, MenubarSubContent, MenubarShortcut |
+| LoadingSpinner | [simple] | — |
 | NavigationMenu | [complex] | NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink, NavigationMenuIndicator, NavigationMenuViewport, navigationMenuTriggerStyle |
 | NativeSelect | [simple] | NativeSelectOption, NativeSelectOptGroup |
 | Pagination | [composed] | PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis |
@@ -570,12 +570,12 @@ These are styling behaviors you can't discover from TypeScript types alone:
 | Tabs | **Variants:** `default` (pill, `bg-tabs`) and `line` (underline, transparent bg). **Sizes:** `sm` (h-8, text-xs), `md` (h-10, text-sm, default), `lg` (h-12, text-base). **Icon position:** `inline` (default) or `top` (stacks icon above label). **Orientation:** `horizontal` (default) or `vertical` (line variant renders left-edge indicator). Hover: `bg-secondary-hover` (default) / `text-primary` (line). Selected: `bg-tabs-active` + `text-primary font-semibold`. Line variant underline: `bg-primary`. |
 | Select | Item hover: `bg-primary/[0.08]`. Selected: `text-primary font-medium` + checkmark. `SelectTrigger` accepts `readOnly` prop: blocks interaction, retains full default appearance, chevron renders at `opacity-30` |
 | Progress | Track: `bg-primary/20`. Indicator: `bg-primary`. Radius: `rounded-2xs` |
-| Spinner | Inherits parent text color. **Always pass `text-primary` for standalone use** |
+| LoadingSpinner | Arc spinner. Color comes from `--loading-spinner-bg-default` token (coral `#ff444f`). Size defaults to `size-4` (16px); override via `className` (e.g. `size-6`, `size-8`). |
 | Stepper | Numeric input flanked by `−` / `+` tertiary `icon-xs` buttons. Composes `InputGroup` internally. Props: `value`, `defaultValue`, `onValueChange`, `min`, `max`, `step` (default 1), `disabled`, `placeholder`. Supports controlled & uncontrolled modes, keyboard Arrow Up/Down, and floating-point steps. Default width: `w-32` |
 | Switch | Checked track: `bg-slider-range`. Checked thumb: `bg-primary` |
 | Slider | Thumb: square `rounded-[4px]`, `bg-primary`. Track range: `bg-slider-range` |
 | Dialog/Sheet | Footer buttons should use `size="md"`. Overlay: `bg-overlay` |
-| Menubar | Hover: `bg-primary/[0.08]`. Open state: `bg-primary/10` |
+| Link | **5 variants:** `primary` (coral, theme-agnostic), `secondary-normal` (dark on light / auto-switches to inverse white on dark mode), `secondary-inverse` (white, always for dark backgrounds), `secondary-static-light` (always dark, light backgrounds), `secondary-static-dark` (always white, dark backgrounds). Always underlined. Sizes: `sm` (12px), `md` (14px), `lg` (16px, default). Disabled via `aria-disabled="true"`. |
 | Toggle | Pressed: `bg-primary/10` + `border-primary` + `text-primary` |
 | Calendar | Selected: `bg-secondary-hover` + `text-primary font-bold`. Today: primary dot below date |
 
@@ -585,7 +585,7 @@ These are styling behaviors you can't discover from TypeScript types alone:
 
 > Blocks are fully composed UI sections built from design system primitives. They appear in the **Blocks** tab of the playground.
 > - Blocks are **NOT exported** from the npm package — they are playground demonstrations only.
-> - To build them in a consuming project, import the underlying components (`Button`, etc.) from `@trading-game/design-intelligence-layer` and compose them manually using design tokens only.
+> - To build them in a consuming project, import the underlying components (`Button`, etc.) from `@deriv-ds/design-intelligence-layer` and compose them manually using design tokens only.
 > - Do NOT mistake a Block for a component — it will not appear in Rule 1's component list.
 
 ### NavBar