diff --git a/.agents/skills/sgds-components/reference/accordion.md b/.agents/skills/sgds-components/reference/accordion.md index 45db1888..651eb3b4 100644 --- a/.agents/skills/sgds-components/reference/accordion.md +++ b/.agents/skills/sgds-components/reference/accordion.md @@ -74,6 +74,12 @@ Accordion items support two expand modes: **Compact spacing?** → `density="compact"` on `` +**Spacious spacing?** → `density="spacious"` on `` + +**Icon before the header?** → Use the `icon` slot on `` + +**Badge after the header?** → Use the `badge` slot on `` + **Start an item open?** → Add `open` on `` ```html @@ -112,6 +118,22 @@ Accordion items support two expand modes:
Content B.
 + + + + + +
Section with icon
+ New +
Content here.
+ + + +
Another section
+ Updated +
More content here.
+ + ``` ## API Summary @@ -122,7 +144,7 @@ Accordion items support two expand modes: |---|---|---|---| | `allowMultiple` | boolean | `false` | Allows multiple items to be open simultaneously | | `variant` | `default \| border` | `default` | Visual style of the accordion | -| `density` | `default \| compact` | `default` | Spacing density of accordion items | +| `density` | `default \| compact \| spacious` | `default` | Spacing density of accordion items | ### `` @@ -135,9 +157,11 @@ Accordion items support two expand modes: | Slot | Purpose | |---|---| +| `icon` | An icon placed before the header text | | `header` | The clickable header / title of the accordion item | -| `content` | The body content shown when the item is expanded | +| `badge` | A badge placed after the header text, aligned to the right | | `caret` | Custom caret/icon replacing the default chevron | +| `content` | The body content shown when the item is expanded | ## Events (``) diff --git a/.agents/skills/sgds-components/reference/alert.md b/.agents/skills/sgds-components/reference/alert.md index aa947da4..07d36bd2 100644 --- a/.agents/skills/sgds-components/reference/alert.md +++ b/.agents/skills/sgds-components/reference/alert.md @@ -41,12 +41,13 @@ No CSS styling modifications — custom properties and CSS parts are not exposed ## Component Composition -**`icon` slot** — a single `` that matches the alert's semantic variant: -- `info` → `` -- `success` → `` -- `danger` → `` -- `warning` → `` +**`icon` slot** — a single `` that matches the alert's semantic variant: +- `info` → `` +- `success` → `` +- `danger` → `` +- `warning` → `` - Omit the slot entirely for a text-only (no icon) alert. +- Always set `size="md"` on the icon — this is the required size for alert icons. **Default slot (body)** — paragraph text and `` elements for inline links. Basic HTML is permitted (``, ``, `

`). Avoid placing interactive components in the body — alerts are informational only. @@ -109,40 +110,40 @@ No CSS styling modifications — custom properties and CSS parts are not exposed ```html - +

Description with link
- +
Operation completed.
 - +
Something went wrong.
 - +
Proceed with caution.
 - +
Here is some information.
 - +
Outlined alert.
 - +
This alert can be closed.
 @@ -202,7 +203,7 @@ For framework-specific event syntax (React, Vue, Angular) see the **[sgds-compon **For AI agents**: 1. Always use `` for feedback messages — never suggest custom `
` banners. 2. `show` must be set to `true` for the alert to be visible regardless of whether it is `dismissible`. -3. The `icon` slot is optional; omit it for a text-only alert. +3. The `icon` slot is optional; omit it for a text-only alert. When using it, always set `size="md"` on the ``. 4. Use `` (not a plain `` tag) for any link inside the alert body. 5. `title` accepts plain text only — do not pass HTML into the `title` attribute. 6. `close()` programmatically dismisses the alert; listening for `sgds-hide` confirms it has closed. diff --git a/.agents/skills/sgds-writing/SKILL.md b/.agents/skills/sgds-writing/SKILL.md new file mode 100644 index 00000000..b2856fcd --- /dev/null +++ b/.agents/skills/sgds-writing/SKILL.md @@ -0,0 +1,282 @@ +--- +name: "sgds-writing" +description: "Writing style guide for the Singapore Government Design System (SGDS). Use when writing or reviewing UI copy, documentation, labels, error messages, tooltips, or any content that accompanies SGDS components. Covers tone, grammar, spelling, casing, punctuation, and plain language principles." +metadata: + author: singapore-design-system + version: "0.0.0" + audience: external + category: content +--- + +# SGDS Writing Guide + +Content standards for government digital products built with the Singapore Government Design System. Apply these rules to all UI copy, documentation, tooltips, labels, error messages, and any written content that accompanies SGDS components. + +--- + +## Tone and voice + +Write as a trusted, competent partner — not as a bureaucracy. GovTech's voice is: + +- **Clear** — say exactly what you mean in as few words as needed +- **Direct** — address the reader as "you"; use active voice +- **Respectful** — treat readers as capable adults; do not over-explain +- **Purposeful** — every sentence earns its place; remove filler + +Avoid corporate jargon ("leverage", "synergise", "holistic approach"), hollow intensifiers ("very", "extremely", "crucial"), and vague forward-looking language ("innovative", "cutting-edge", "future-proof") unless the context genuinely calls for them. + +**Preferred:** We help agencies share data securely. +**Avoid:** We leverage cutting-edge, innovative solutions to holistically enable seamless data exchange across government agencies. + +--- + +## Spelling + +Use **UK English** spelling throughout. + +| UK (correct) | US (avoid) | +|---|---| +| colour | color | +| centre | center | +| programme | program (unless referring to software) | +| organisation | organization | +| recognise | recognize | +| analyse | analyze | +| catalogue | catalog | +| licence (noun) | license (noun) | +| license (verb) | licence (verb) | +| travelled | traveled | +| fulfil | fulfill | +| practise (verb) | practice (verb) | +| practice (noun) | practise (noun) | + +> **Spell-check setting**: set your editor and CI spell checker to `en-GB`. In VS Code, set `"editor.language": "en-GB"` or use the [Spell Right](https://marketplace.visualstudio.com/items?itemName=ban.spellright) extension with `"spellright.language": ["en-GB"]`. + +See [→ reference/spelling.md](reference/spelling.md) for a full word list. + +--- + +## Capitalisation + +Use **sentence case** for all headings, labels, button text, navigation items, error messages, and body copy — unless a rule below explicitly overrides it. + +Sentence case means: capitalise the first word and proper nouns only. + +**Correct:** +- Submit your application +- View all services +- Error: file size exceeds the limit + +**Incorrect (title case):** +- Submit Your Application +- View All Services +- Error: File Size Exceeds the Limit + +### Exceptions where capitalisation is required + +- Proper nouns: GovTech, SingPass, CorpPass, Smart Nation, Singapore, Ministry of Finance +- Acronyms that are always written in capitals: API, ICT, UI, UX, PDF, URL +- Product and system names that have an established capitalisation: Singpass, CorpPass, MyInfo +- The word "I" when used as a pronoun + +### Do not capitalise + +- Job titles used descriptively: "the director approved the request" (capitalise only when used as a title directly before a name: "Director Jane Tan approved the request") +- Government services or programmes used generically: "the digital identity programme", "the data-sharing initiative" +- Seasons, directions, or concepts: "the autumn release", "head north on the main road" + +--- + +## Punctuation + +### No em dash + +Do not use the em dash (—) under any circumstances. It creates visual noise and is often misread or skipped by screen readers. + +**Alternatives:** + +| Instead of | Use | +|---|---| +| The form — which is required — must be submitted by Friday. | The form, which is required, must be submitted by Friday. | +| Submit before Friday — or your application will lapse. | Submit before Friday. Otherwise, your application will lapse. | +| Three options — email, phone, or in person — are available. | Three options are available: email, phone, or in person. | + +Use a colon, comma pair, or a new sentence. Never an em dash. + +### Commas + +Use the Oxford comma (serial comma) in lists of three or more items. + +**Correct:** You will need your NRIC, passport, and proof of address. +**Incorrect:** You will need your NRIC, passport and proof of address. + +### Hyphens and en dashes + +- Use a hyphen (-) for compound modifiers before a noun: "user-friendly interface", "end-to-end encryption" +- Use an en dash (–) only for number ranges: "pages 10–15", "2020–2024" +- Do not use an en dash as a substitute for an em dash + +### Apostrophes + +- Use for possessives: the agency's portal, the user's profile +- Do not use for plurals: APIs not API's, PDFs not PDF's + +### Colons and semicolons + +- Colons introduce lists or explanations. Do not capitalise the word after a colon unless it is a proper noun or the start of a full sentence that stands alone. +- Use semicolons sparingly. Prefer two short sentences over a semicolded compound sentence. + +--- + +## Grammar + +### Active voice + +Prefer active voice. The subject acts; it is not acted upon. + +**Active:** The system sends a confirmation email. +**Passive:** A confirmation email is sent by the system. + +Passive voice is acceptable when the actor is unknown, irrelevant, or less important than the action: "Your data is encrypted at rest." + +### No contrastive negation + +Do not use contrastive negation — the pattern "not X, but Y" or "not only X but also Y". It adds a negation step that slows reading. + +**Avoid:** +- Not a bug tracker, but a full project management tool. +- This is not optional, but mandatory. +- We do not just build tools — we build trust. + +**Preferred:** +- A full project management tool that also tracks bugs. +- This is mandatory. +- We build tools that earn trust. + +### Sentence length + +Aim for sentences under 20 words. If a sentence needs a clause to clarify another clause, split it into two sentences. + +### Parallel structure + +Items in a list, heading pairs, and button labels must follow the same grammatical form. + +**Correct (all verb phrases):** +- Create a new account +- Reset your password +- View your transaction history + +**Incorrect (mixed forms):** +- Create a new account +- Password reset +- Viewing your transaction history + +### Contractions + +Do not use contractions in any content. Write out the full form at all times. + +**Correct:** You do not need to create an account. +**Incorrect:** You don't need to create an account. + +**Correct:** We have updated the interface. +**Incorrect:** We've updated the interface. + +> **Note:** This is a deliberate departure from most product design system guides. GOV.UK, Canada.ca, Shopify Polaris, and Apple HIG all recommend using contractions on the grounds that they sound more natural. We avoid them to maintain formal, consistent language appropriate for official Singapore Government products, and to eliminate ambiguity (for example, "it's" vs "its"). + +### Modal verbs — must, need to, should, may + +Use modal verbs precisely. The wrong choice creates unintended legal obligations or false reassurances. + +| Word | When to use | Example | +|---|---|---| +| **Must** | Legal obligation — the user has no choice | You must submit the form by 31 January. | +| **Need to** | An administrative step the user is expected to complete | You need to verify your email before signing in. | +| **Should** | A recommendation — the user is advised but not obligated | You should save your progress regularly. | +| **May** | Permitted but optional | You may attach supporting documents. | + +Do not use "must" for administrative steps — it implies a legal consequence that may not exist. Do not use "should" when the step is actually required. + +### Numbers + +- Spell out numbers one to nine; use numerals for 10 and above. +- Always use numerals for: percentages (5%), currency ($10), measurements (3 MB), and version numbers (version 2). +- Use commas in numbers of 1,000 or more: 1,000 not 1000. +- Use numerals for ranges even if both numbers are below 10: "3–9 working days". + +### Dates and times + +- Dates: 1 January 2025 (day month year, no ordinal suffixes — not "1st January") +- Times: 9am, 3:30pm (no space between number and am/pm) +- Date ranges in prose: 1 to 3 January 2025 (write "to", not an en dash) +- Date ranges in tables and compact UI elements: 1–3 Jan 2025 (en dash is acceptable where space is limited) + +--- + +## Plain language principles + +1. **Lead with the most important information.** Put the key point in the first sentence. +2. **One idea per paragraph.** If a paragraph covers two ideas, split it. +3. **Cut filler.** Remove "please note that", "it should be noted", "in order to", "at this point in time". +4. **Prefer short words.** Use "use" not "utilise", "help" not "facilitate", "buy" not "procure", "show" not "demonstrate". +5. **Avoid nominalisations.** Change "make a decision" to "decide"; "provide assistance" to "help"; "conduct an investigation" to "investigate". +6. **Do not use "please" in instructions.** It adds no information and reads as hedging. Write "Submit the form" not "Please submit the form". The exception is expressions of genuine courtesy in transactional emails or formal correspondence. +7. **Do not use subjective adjectives.** Do not tell users that something is "important", "easy", "simple", "quick", or "exciting". If it is important, show why. If it is simple, let the design demonstrate that. Subjective claims that cannot be verified erode trust. + +--- + +## UI copy patterns + +### Buttons and calls to action + +- Use verb phrases: "Submit form", "Download report", "Sign in" +- Do not use vague labels: "Click here", "OK", "Go" +- Do not add punctuation to button labels + +### Error messages + +- State what happened and what the user should do next. +- Do not blame the user. + +**Correct:** The file is too large. Upload a file under 5 MB. +**Incorrect:** You uploaded a file that is too large. Please upload a smaller file. + +### Empty states + +- Explain why the space is empty and offer a next step. + +**Correct:** No applications yet. Start your first application. +**Incorrect:** Nothing here. + +### Tooltips and helper text + +- Keep tooltips to one sentence. +- Helper text below a field explains the format or constraint, not a restatement of the label. + +**Label:** Date of birth +**Helper text:** Use DD/MM/YYYY format +**Not:** Enter your date of birth in DD/MM/YYYY format + +### Loading and status messages + +- Use present progressive: "Loading your results…", "Saving changes…" +- Confirm success with past tense: "Changes saved.", "Application submitted." + +--- + +## Accessibility considerations + +- Do not rely on colour alone to convey meaning — always pair colour with text. +- Alt text for images should describe function, not appearance: "GovTech logo" not "blue rectangular image with text". +- Link text must make sense out of context: "Download the annual report (PDF, 2 MB)" not "click here". +- Avoid directional instructions that rely on visual layout: "see the section on the right" does not work for screen-reader users. + +--- + +## Reference files + +| Topic | File | +|---|---| +| UK vs US spelling word list | [→ reference/spelling.md](reference/spelling.md) | +| Grammar rules quick reference | [→ reference/grammar.md](reference/grammar.md) | +| Punctuation quick reference | [→ reference/punctuation.md](reference/punctuation.md) | +| Word choice and plain language | [→ reference/word-choice.md](reference/word-choice.md) | diff --git a/.agents/skills/sgds-writing/reference/grammar.md b/.agents/skills/sgds-writing/reference/grammar.md new file mode 100644 index 00000000..6cc512d9 --- /dev/null +++ b/.agents/skills/sgds-writing/reference/grammar.md @@ -0,0 +1,143 @@ +# Grammar quick reference + +## Active vs passive voice + +Write in active voice by default. The subject performs the action. + +| Active (preferred) | Passive (avoid unless necessary) | +|---|---| +| The system sends a confirmation email. | A confirmation email is sent by the system. | +| GovTech built this service. | This service was built by GovTech. | +| Submit the form before Friday. | The form should be submitted before Friday. | + +Passive is acceptable when: +- The actor is unknown: "Your data is encrypted at rest." +- The actor is irrelevant: "The application was approved." +- You deliberately want to soften accountability in formal notices. + +--- + +## Contrastive negation — do not use + +Contrastive negation is the pattern "not X, but Y" or "not X — Y". It forces the reader to hold a negative while processing a positive. Replace it with a direct positive statement. + +| Avoid | Preferred | +|---|---| +| Not a bug tracker, but a full project management tool. | A full project management tool that also tracks bugs. | +| This is not optional, but mandatory. | This is mandatory. | +| Not just for developers, but for everyone. | Built for everyone, including developers. | +| We don't just build tools — we build trust. | We build tools that earn trust. | +| This is not a limitation — it's a feature. | This is a deliberate feature. | + +The rule extends to "not only… but also…" constructions. Rewrite to lead with the more important claim. + +| Avoid | Preferred | +|---|---| +| Not only does it save time, but it also reduces errors. | It saves time and reduces errors. | + +--- + +## Parallel structure + +All items in a series must follow the same grammatical form. Check headings, navigation labels, list items, and button labels. + +**Correct (all imperative verb phrases):** +- Create an account +- Reset your password +- View transaction history + +**Incorrect (mixed):** +- Create an account +- Password reset ← noun phrase +- Viewing transaction history ← gerund + +**Correct (all noun phrases):** +- Account creation +- Password reset +- Transaction history + +--- + +## Sentence length + +Target: under 20 words per sentence. Count when in doubt. + +Long sentences usually fail for one of two reasons: +1. Multiple clauses that could be separate sentences +2. Hedging language that can be deleted entirely + +**Before:** In order to ensure that your application is processed in a timely manner, please make sure that all required documents have been attached prior to submission. + +**After:** Attach all required documents before you submit. This helps us process your application faster. + +--- + +## Contractions + +Do not use contractions. Write out the full form in all content — UI copy, documentation, labels, and error messages. + +| Correct | Incorrect | +|---|---| +| You do not need an account. | You don't need an account. | +| We have updated the interface. | We've updated the interface. | +| It is available to all agencies. | It's available to all agencies. | +| It does not apply here. | It doesn't apply here. | + +This applies everywhere without exception. Formal, consistent language reinforces credibility and avoids ambiguity (for example, "it's" versus "its"). + +> **Industry context:** GOV.UK, Canada.ca, Shopify Polaris, and Apple HIG all recommend using contractions. This guide deliberately departs from that position to maintain the formal register appropriate for official Singapore Government products. + +--- + +## Modal verbs — must, need to, should, may + +Use modal verbs precisely. The wrong choice creates unintended legal implications or understates genuine obligations. + +| Word | Meaning | When to use | Example | +|---|---|---|---| +| **Must** | Legal obligation — no choice | Legal requirement set out in legislation or policy | You must submit your tax return by 31 January. | +| **Need to** | Expected step — administrative | A step the user is expected to complete to proceed | You need to verify your email before signing in. | +| **Should** | Recommendation — advised but not required | Best practice or strong suggestion | You should save your progress regularly. | +| **May** | Permission — optional | The user is allowed but not required | You may attach supporting documents. | + +**Common mistakes:** + +| Incorrect | Correct | Why | +|---|---|---| +| You must verify your email. | You need to verify your email. | Email verification is administrative, not a legal obligation. | +| You should submit by Friday. | You must submit by Friday. | If Friday is a hard deadline, "should" understates it. | +| You can attach documents. | You may attach documents. | "Can" expresses ability; "may" expresses permission. | + +--- + +## Nominalisations + +A nominalisation turns a verb into a noun, making sentences longer and more abstract. Replace nominalisations with their verb forms. + +| Nominalisation (avoid) | Verb form (preferred) | +|---|---| +| make a decision | decide | +| provide assistance | help | +| conduct an investigation | investigate | +| give consideration to | consider | +| reach an agreement | agree | +| make an improvement | improve | +| carry out a review | review | +| achieve a reduction | reduce | + +--- + +## Subject-verb agreement with collective nouns + +Treat collective nouns as singular in formal writing: +- "The team is reviewing the proposal." (not "are reviewing") +- "The government has announced…" (not "have announced") + +--- + +## That vs which + +- Use "that" for restrictive clauses (defines or limits the subject): "The file that you uploaded is too large." +- Use "which" for non-restrictive clauses, set off by commas (adds information): "The file, which is 10 MB, is too large." + +When in doubt, use "that" and drop the comma. diff --git a/.agents/skills/sgds-writing/reference/punctuation.md b/.agents/skills/sgds-writing/reference/punctuation.md new file mode 100644 index 00000000..486bd8d0 --- /dev/null +++ b/.agents/skills/sgds-writing/reference/punctuation.md @@ -0,0 +1,121 @@ +# Punctuation quick reference + +## Em dash — never use + +The em dash (—) is banned. It creates visual noise, is frequently misread, and causes accessibility issues with some screen readers. + +When you feel the urge to use an em dash, reach for one of these instead: + +| Situation | Use instead | Example | +|---|---|---| +| Parenthetical aside | Comma pair | The form, which is required, must be submitted by Friday. | +| Abrupt break or afterthought | New sentence | Submit before Friday. Otherwise, your application will lapse. | +| Introducing a list | Colon | Three options are available: email, phone, or in person. | +| Amplification or elaboration | Colon or new sentence | There is one exception: users who registered before 2020. | + +Never substitute an en dash (–) for an em dash to work around this rule. En dashes have a specific and limited role — see below. + +--- + +## En dash + +Use the en dash (–) for: +- Number ranges in tables and compact UI: pages 10–15, 9am–5pm +- Score or versus relationships: Singapore–Malaysia collaboration + +No spaces around an en dash in ranges. + +**Date ranges:** Write "to" in prose — "1 to 3 January 2025", not "1–3 January 2025". The en dash is acceptable in tables and compact UI elements where space is limited. This matches GOV.UK and Canada.ca conventions. + +--- + +## Hyphen + +Use the hyphen (-) for: +- Compound modifiers before a noun: user-friendly interface, end-to-end encryption, whole-of-government approach +- Some prefixes where omission creates ambiguity: re-enter, co-ordinate, pre-existing + +Do not hyphenate: +- Adverb + adjective combinations: "a fully integrated system" (not "fully-integrated system") +- Compound modifiers that follow the noun: "the interface is user friendly" (no hyphen) + +--- + +## Oxford comma (serial comma) + +Always use the Oxford comma in lists of three or more items. + +**Correct:** You will need your NRIC, passport, and proof of address. +**Incorrect:** You will need your NRIC, passport and proof of address. + +The Oxford comma prevents ambiguity and is standard in this guide. + +--- + +## Full stops (periods) + +- End all complete sentences with a full stop. +- Do not add a full stop after button labels, headings, navigation items, or form labels. +- Do not add a full stop after a single-item list or a standalone sentence in a tooltip. +- In bulleted lists: if each item is a full sentence, end with a full stop. If items are fragments, no full stop. + +--- + +## Colons + +- Use to introduce a list or an explanation. +- Do not capitalise the word after a colon unless it is a proper noun or the start of an independently complete sentence. + +**Correct:** Submit the following: NRIC, proof of address, and a recent photograph. +**Correct:** There is one rule: never share your password. +**Incorrect:** Submit: Your NRIC, proof of address, and photograph. + +--- + +## Semicolons + +Use sparingly. In most cases, two short sentences are clearer than a semicoloned compound sentence. + +**Acceptable:** The portal handles both tasks; it validates and submits in one step. +**Often better:** The portal handles both tasks. It validates and submits in one step. + +Do not use semicolons in bullet lists. + +--- + +## Quotation marks + +Use double quotation marks for direct speech and quotations. +Use single quotation marks for a word used as a term or concept: The word 'submit' appears on every form. + +In UI copy, avoid quotation marks altogether — rephrase instead. + +--- + +## Apostrophes + +| Use | Correct | Incorrect | +|---|---|---| +| Contraction | it's, you're, we've | its' | +| Possessive | the agency's portal | the agencys portal | +| Plural | APIs, PDFs, the 1990s | API's, PDF's, the 1990's | + +"Its" (possessive pronoun) never takes an apostrophe: "The system updated its records." + +--- + +## Brackets + +Use brackets (parentheses) sparingly. If the content inside the brackets is important enough to include, it is usually important enough to be in the main sentence. + +Square brackets [ ] are reserved for editorial insertions in quotations. + +--- + +## Ellipsis + +Use an ellipsis (…) only in: +- Loading state messages: "Loading your results…" +- Truncated text in UI components (applied programmatically) + +Do not use ellipsis for stylistic effect or to imply a trailing thought. diff --git a/.agents/skills/sgds-writing/reference/spelling.md b/.agents/skills/sgds-writing/reference/spelling.md new file mode 100644 index 00000000..56532b7e --- /dev/null +++ b/.agents/skills/sgds-writing/reference/spelling.md @@ -0,0 +1,81 @@ +# UK English spelling reference + +Set your spell checker to `en-GB`. This list covers words that commonly appear in government digital products and UI copy where UK and US spellings diverge. + +## Common word list + +| UK (correct) | US (avoid) | Notes | +|---|---|---| +| acknowledgement | acknowledgment | | +| adviser | advisor | preferred UK form | +| ageing | aging | | +| analyse | analyze | and all -yse/-yze verbs | +| behaviour | behavior | | +| cancelled | canceled | double-l in past tense | +| catalogue | catalog | | +| centre | center | | +| cheque | check | financial instrument | +| colour | color | and all -our/-or words | +| defence | defense | noun form | +| dialogue | dialog | except in UI (see note) | +| draught | draft | for the noun meaning a current of air | +| endeavour | endeavor | | +| favour | favor | | +| fibre | fiber | | +| flavour | flavor | | +| fulfil | fulfill | single-l | +| grey | gray | | +| harbour | harbor | | +| honour | honor | | +| humour | humor | | +| judgement | judgment | both acceptable; prefer judgement | +| labour | labor | | +| licence | license | noun only; verb is "license" | +| litre | liter | | +| mould | mold | | +| neighbourhood | neighborhood | | +| organise | organize | and all -ise/-ize verbs (see note) | +| organisation | organization | | +| practise | practice | verb only; noun is "practice" | +| programme | program | use "program" only for software | +| realise | realize | | +| recognise | recognize | | +| rumour | rumor | | +| sceptical | skeptical | | +| signalling | signaling | double-l | +| specialise | specialize | | +| travelling | traveling | double-l | +| tyre | tire | rubber on a wheel | +| vapour | vapor | | + +## -ise vs -ize + +UK English accepts both -ise and -ize for most verbs (organise/organize, recognise/recognize). This guide standardises on **-ise** for consistency. Do not mix forms in the same document. + +## "Dialog" exception + +In UI copy that refers to a dialog box (the UI component), use "dialog" not "dialogue" — this is an accepted technical term and matches the HTML `` element and common accessibility vocabulary. + +## Spell-checker setup + +### VS Code +Install the [Spell Right](https://marketplace.visualstudio.com/items?itemName=ban.spellright) extension and add to your workspace settings: + +```json +{ + "spellright.language": ["en-GB"], + "spellright.documentTypes": ["markdown", "plaintext", "html"] +} +``` + +### cspell (Node.js / CI) +Add to `cspell.json`: + +```json +{ + "language": "en-GB", + "dictionaries": ["en-gb"] +} +``` + +Install the GB dictionary: `npm install --save-dev @cspell/dict-en-gb` diff --git a/.agents/skills/sgds-writing/reference/word-choice.md b/.agents/skills/sgds-writing/reference/word-choice.md new file mode 100644 index 00000000..ad77d497 --- /dev/null +++ b/.agents/skills/sgds-writing/reference/word-choice.md @@ -0,0 +1,184 @@ +# Word choice and plain language + +## Prefer short, common words + +Replace formal or bureaucratic vocabulary with plain alternatives. + +| Avoid | Use instead | +|---|---| +| utilise | use | +| facilitate | help, enable | +| procure | buy | +| demonstrate | show | +| commence | start, begin | +| terminate | end, stop | +| endeavour | try | +| ascertain | find out | +| notify | tell, let know | +| request | ask for | +| obtain | get | +| sufficient | enough | +| additional | more | +| approximately | about | +| in the event that | if | +| prior to | before | +| subsequent to | after | +| in order to | to | +| due to the fact that | because | +| at this point in time | now | +| on a regular basis | regularly | +| with the exception of | except | +| in relation to | about | +| make a decision | decide | +| provide assistance | help | +| conduct a review | review | +| give consideration to | consider | +| take into account | consider | + +--- + +## Cut filler phrases + +These phrases add length without meaning. Delete them entirely. + +- Please note that… +- It should be noted that… +- It is important to mention that… +- We would like to inform you that… +- For your information… +- As mentioned above / as noted earlier… +- In conclusion… +- Needless to say… + +## Do not use "please" in instructions + +"Please" adds no information and reads as hedging in instructional copy. Remove it. + +**Correct:** Submit the form before Friday. +**Incorrect:** Please submit the form before Friday. + +**Correct:** Attach all required documents. +**Incorrect:** Please attach all required documents. + +The exception is expressions of genuine courtesy in transactional emails or formal correspondence where a human is addressing another human directly. + +## Do not use subjective adjectives + +Do not tell users that something is "important", "easy", "simple", "quick", "exciting", "straightforward", or "great". These claims cannot be verified and erode trust when the user's experience does not match the description. + +**Incorrect:** This simple process takes just a few minutes. +**Correct:** This process has three steps. + +**Incorrect:** Easily manage your account settings. +**Correct:** Manage your account settings. + +**Incorrect:** Important: submit before Friday. +**Correct:** Submit before Friday. (If it is truly critical, use a visual alert component, not the word "important".) + +If something matters, show why through clear structure and content — not through adjectives. + +## Avoid Latin abbreviations + +Write out Latin abbreviations in full. They are not universally understood and can confuse non-native English readers. + +| Avoid | Write instead | +|---|---| +| e.g. | for example | +| i.e. | that is | +| etc. | and so on (use sparingly; it implies you ran out of ideas — list all items or use "including") | +| via | through, by, using | +| vs. | versus, compared to, or | +| N.B. | Note: | + +--- + +## Jargon to avoid + +These words appear frequently in government communications but weaken the writing. + +| Jargon | Why to avoid | Alternative | +|---|---|---| +| leverage | Means "use" — say so | use, apply | +| synergise | Means "work together" — say so | work together, combine | +| holistic | Vague amplifier | specify what you mean | +| seamless | Overused; says nothing specific | describe the actual benefit | +| innovative | Claims distinction without evidence | describe what is new or different | +| cutting-edge | Overused marketing language | describe the specific capability | +| robust | Vague; often means "good" | specify what makes it reliable | +| scalable | Acceptable in technical context; avoid in user-facing copy | describe what scales and why | +| ecosystem | Metaphor that obscures meaning | describe the actual system or set of services | +| empower | Overused; often patronising | describe the actual capability given to users | +| transformative | Means "big change" — describe the change instead | describe what specifically changes | +| stakeholder | Acceptable internally; use "people", "teams", or "agencies" in user-facing copy | people, teams, agencies | + +--- + +## Inclusive language + +- Use "they/them" for singular subjects of unknown gender. Do not use "he/she" or "s/he". +- Write "people with disabilities" not "disabled people" or "the disabled" (person-first language; follow the individual's preference where known). +- Use "older people" not "the elderly". +- Avoid culturally specific idioms that do not translate: "ball park figure", "hit the ground running", "low-hanging fruit". +- Use "Singapore resident" or "Singapore citizen" precisely — they are not interchangeable. + +--- + +## Numbers + +| Situation | Rule | Example | +|---|---|---| +| One to nine | Spell out | three options, nine agencies | +| 10 and above | Numeral | 10 steps, 45 minutes | +| Start of sentence | Always spell out | Twelve documents are required. | +| Percentages | Always numeral + % | 5% increase, 100% uptime | +| Currency | Numeral + symbol | $10, $1,200 | +| File sizes | Numeral + unit | 3 MB, 500 KB | +| Version numbers | Numeral | version 3, release 2.1 | +| Ranges | Numeral + en dash | 3–9 working days | +| Thousands | Use comma | 1,000 not 1000; 10,000 not 10000 | + +--- + +## Dates and times + +| Element | Format | Example | +|---|---|---| +| Date | Day Month Year | 1 January 2025 | +| Date with day | Day, Day Month Year | Monday, 1 January 2025 | +| Date range in prose | Day to Day Month Year | 1 to 3 January 2025 | +| Date range in prose (different months) | Day Month to Day Month Year | 28 January to 3 February 2025 | +| Date range in tables / compact UI | Day–Day Month Year | 1–3 Jan 2025 | +| Time | Numeral + am/pm | 9am, 3:30pm, 12 noon, 12 midnight | +| Time range | Numeral–numeral + am/pm | 9am–5pm | +| Financial year | FY + year | FY2025 | + +No ordinal suffixes on dates (not "1st January", "3rd March"). +No space between the numeral and am/pm. + +--- + +## Abbreviations and acronyms + +- Spell out in full on first use, with the abbreviation in brackets: Government Technology Agency (GovTech). +- After the first use, the abbreviation alone is fine. +- Do not introduce an abbreviation that you will not use again. +- Do not use an abbreviation if the full term only appears once. +- Plurals of abbreviations: no apostrophe — APIs, PDFs, URLs. +- Common abbreviations that do not need spelling out in a government digital context: NRIC, PDF, URL, API, UI, UX, IT. + +--- + +## Government-specific terms + +| Use | Avoid | Notes | +|---|---|---| +| Singapore Government | the Government (capitalise when referring to SG Government) | | +| GovTech | govtech, GovTech Agency | official short form | +| Singpass | SingPass, SingPASS | check current official capitalisation | +| CorpPass | Corppass | check current official capitalisation | +| MyInfo | My Info, MYINFO | check current official capitalisation | +| Smart Nation | smart nation | proper noun, always capitalised | +| whole-of-government | whole of government | hyphenate as compound modifier | +| digital government | Digital Government | not a proper noun unless in an official title | +| public officer | civil servant | preferred term in SG context | +| agency | ministry / department | use when referring generically; be specific when possible | diff --git a/.gitignore b/.gitignore index 812af4b1..3a345d1d 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,6 @@ .DS_Store node_modules docs/.vitepress/dist -docs/.vitepress/cache \ No newline at end of file +docs/.vitepress/cache +.claude/worktrees +.claude/settings.local.json diff --git a/docs/.vitepress/components/components/AccessibilitySection.vue b/docs/.vitepress/components/components/AccessibilitySection.vue index 80cbe07b..adb21507 100644 --- a/docs/.vitepress/components/components/AccessibilitySection.vue +++ b/docs/.vitepress/components/components/AccessibilitySection.vue @@ -1,7 +1,9 @@ @@ -178,7 +213,9 @@ onBeforeUnmount(() => { /* Global selectors targeting slotted web component elements in v-html markup */ .accessibility-demo-markup > sgds-accordion { background: var(--sgds-surface-default); + border-radius: var(--sgds-border-radius-md); display: block; + overflow: hidden; width: 100%; } diff --git a/docs/.vitepress/components/components/AccordionV2ApiTable.vue b/docs/.vitepress/components/components/AccordionV2ApiTable.vue deleted file mode 100644 index c248db6b..00000000 --- a/docs/.vitepress/components/components/AccordionV2ApiTable.vue +++ /dev/null @@ -1,24 +0,0 @@ - - - diff --git a/docs/.vitepress/components/components/AccordionV2Page.vue b/docs/.vitepress/components/components/AccordionV2Page.vue deleted file mode 100644 index c6bf9268..00000000 --- a/docs/.vitepress/components/components/AccordionV2Page.vue +++ /dev/null @@ -1,282 +0,0 @@ - - - - - diff --git a/docs/.vitepress/components/components/AccordionV2TokenTable.vue b/docs/.vitepress/components/components/AccordionV2TokenTable.vue deleted file mode 100644 index a71ccf32..00000000 --- a/docs/.vitepress/components/components/AccordionV2TokenTable.vue +++ /dev/null @@ -1,23 +0,0 @@ - - - diff --git a/docs/.vitepress/components/components/AlertPlayground.vue b/docs/.vitepress/components/components/AlertPlayground.vue new file mode 100644 index 00000000..f1e66ad9 --- /dev/null +++ b/docs/.vitepress/components/components/AlertPlayground.vue @@ -0,0 +1,232 @@ + + + diff --git a/docs/.vitepress/components/components/AnatomySection.vue b/docs/.vitepress/components/components/AnatomySection.vue index 48c2fd99..0a1c35e9 100644 --- a/docs/.vitepress/components/components/AnatomySection.vue +++ b/docs/.vitepress/components/components/AnatomySection.vue @@ -1,7 +1,8 @@