From 9acdd815d97b3fb035ffe21cb96470f11bdcccce Mon Sep 17 00:00:00 2001 From: Luke Bennett Date: Sat, 29 Aug 2026 12:00:03 +1000 Subject: [PATCH] Make docs examples explain components instead of imagined applications (#528) --- apps/docs/src/examples/blockquote/basic.tsx | 3 +- .../src/examples/blockquote/typography.tsx | 2 +- apps/docs/src/examples/box/basic.tsx | 4 +- apps/docs/src/examples/box/render-element.tsx | 4 +- apps/docs/src/examples/checkbox/states.tsx | 49 ++++++++++++++++--- .../examples/heading/automatic-leveling.tsx | 6 +-- apps/docs/src/examples/heading/basic.tsx | 2 +- apps/docs/src/examples/link/basic.tsx | 2 +- apps/docs/src/examples/link/disabled.tsx | 4 +- apps/docs/src/examples/link/standalone.tsx | 6 +-- apps/docs/src/examples/link/tones.tsx | 21 ++++++-- .../src/examples/loading-skeleton/basic.tsx | 6 +-- .../examples/loading-skeleton/provider.tsx | 6 +-- .../src/examples/loading-spinner/basic.tsx | 2 +- apps/docs/src/examples/numeral/formats.tsx | 2 +- apps/docs/src/examples/prose/basic.tsx | 15 +++--- apps/docs/src/examples/prose/lists.tsx | 10 ++-- apps/docs/src/examples/quote/basic.tsx | 2 +- apps/docs/src/examples/strong/basic.tsx | 2 +- apps/docs/src/examples/text/lead.tsx | 2 +- apps/docs/src/examples/text/transform.tsx | 4 +- apps/docs/src/examples/text/truncation.tsx | 6 ++- docs/DOCUMENTATION.md | 19 +++++-- 23 files changed, 118 insertions(+), 61 deletions(-) diff --git a/apps/docs/src/examples/blockquote/basic.tsx b/apps/docs/src/examples/blockquote/basic.tsx index 77d03dbf..ccdc41bf 100644 --- a/apps/docs/src/examples/blockquote/basic.tsx +++ b/apps/docs/src/examples/blockquote/basic.tsx @@ -3,8 +3,7 @@ import { Blockquote } from '@luke-ui/react/blockquote'; export default () => { return (
- Perfect typography is certainly the most elusive of all arts. Sculpture in stone alone comes - near it in obstinacy. + This passage is set apart from the surrounding text because it comes from another source.
); }; diff --git a/apps/docs/src/examples/blockquote/typography.tsx b/apps/docs/src/examples/blockquote/typography.tsx index 5bd24d27..a5010243 100644 --- a/apps/docs/src/examples/blockquote/typography.tsx +++ b/apps/docs/src/examples/blockquote/typography.tsx @@ -1,5 +1,5 @@ import { Blockquote } from '@luke-ui/react/blockquote'; export default () => { - return
Sphinx of black quartz, judge my vow
; + return
A quoted passage set at the lead size.
; }; diff --git a/apps/docs/src/examples/box/basic.tsx b/apps/docs/src/examples/box/basic.tsx index 7ec0c1c8..c9c904cb 100644 --- a/apps/docs/src/examples/box/basic.tsx +++ b/apps/docs/src/examples/box/basic.tsx @@ -3,8 +3,8 @@ import { Box } from '@luke-ui/react/box'; export default () => { return ( - Account - Settings + First + Second ); }; diff --git a/apps/docs/src/examples/box/render-element.tsx b/apps/docs/src/examples/box/render-element.tsx index cb6599f2..a613a65f 100644 --- a/apps/docs/src/examples/box/render-element.tsx +++ b/apps/docs/src/examples/box/render-element.tsx @@ -3,8 +3,8 @@ import { Box } from '@luke-ui/react/box'; export default () => { return (
}> - Delivery details -

Your order will arrive within three business days.

+ More details +

This content is revealed when the details element is expanded.

); }; diff --git a/apps/docs/src/examples/checkbox/states.tsx b/apps/docs/src/examples/checkbox/states.tsx index a007c158..1606e98a 100644 --- a/apps/docs/src/examples/checkbox/states.tsx +++ b/apps/docs/src/examples/checkbox/states.tsx @@ -1,17 +1,50 @@ import { Box } from '@luke-ui/react/box'; import { Checkbox } from '@luke-ui/react/checkbox'; +import { Text } from '@luke-ui/react/text'; export default () => { return ( - Unchecked - Checked - Indeterminate - Disabled - - Disabled and checked - - Invalid + + + Unchecked + + Example checkbox + + + + Checked + + Example checkbox + + + + Indeterminate + + Example checkbox + + + + Disabled + + Example checkbox + + + + Disabled and checked + + + Example checkbox + + + + + Invalid + + + Example checkbox + + ); }; diff --git a/apps/docs/src/examples/heading/automatic-leveling.tsx b/apps/docs/src/examples/heading/automatic-leveling.tsx index 9a78855a..40db7cc7 100644 --- a/apps/docs/src/examples/heading/automatic-leveling.tsx +++ b/apps/docs/src/examples/heading/automatic-leveling.tsx @@ -5,11 +5,11 @@ export default () => { return ( - Product roadmap + Top-level heading (h1) - Objectives + Nested heading (h2) - First quarter + Nested again (h3) diff --git a/apps/docs/src/examples/heading/basic.tsx b/apps/docs/src/examples/heading/basic.tsx index 8a5a4657..3cdecfbf 100644 --- a/apps/docs/src/examples/heading/basic.tsx +++ b/apps/docs/src/examples/heading/basic.tsx @@ -1,5 +1,5 @@ import { Heading } from '@luke-ui/react/heading'; export default () => { - return Account settings; + return Section heading; }; diff --git a/apps/docs/src/examples/link/basic.tsx b/apps/docs/src/examples/link/basic.tsx index 208b34be..4010fe80 100644 --- a/apps/docs/src/examples/link/basic.tsx +++ b/apps/docs/src/examples/link/basic.tsx @@ -1,5 +1,5 @@ import { Link } from '@luke-ui/react/link'; export default () => { - return Help centre; + return Example destination; }; diff --git a/apps/docs/src/examples/link/disabled.tsx b/apps/docs/src/examples/link/disabled.tsx index b99ab9c4..7c293379 100644 --- a/apps/docs/src/examples/link/disabled.tsx +++ b/apps/docs/src/examples/link/disabled.tsx @@ -2,8 +2,8 @@ import { Link } from '@luke-ui/react/link'; export default () => { return ( - - View archived report + + Example destination ); }; diff --git a/apps/docs/src/examples/link/standalone.tsx b/apps/docs/src/examples/link/standalone.tsx index d69dad17..2845049a 100644 --- a/apps/docs/src/examples/link/standalone.tsx +++ b/apps/docs/src/examples/link/standalone.tsx @@ -6,10 +6,10 @@ export default () => { return ( - Read the release notes before updating your workspace. + An inline example link sits within a sentence. - - Manage members + + Standalone example link ); diff --git a/apps/docs/src/examples/link/tones.tsx b/apps/docs/src/examples/link/tones.tsx index 85980dd3..6bf50675 100644 --- a/apps/docs/src/examples/link/tones.tsx +++ b/apps/docs/src/examples/link/tones.tsx @@ -1,13 +1,24 @@ import { Box } from '@luke-ui/react/box'; import { Link } from '@luke-ui/react/link'; +import { Text } from '@luke-ui/react/text'; export default () => { return ( - - View report - - View report - + + + + Accent + + Example destination + + + + Neutral + + + Example destination + + ); }; diff --git a/apps/docs/src/examples/loading-skeleton/basic.tsx b/apps/docs/src/examples/loading-skeleton/basic.tsx index e3eebc07..55354226 100644 --- a/apps/docs/src/examples/loading-skeleton/basic.tsx +++ b/apps/docs/src/examples/loading-skeleton/basic.tsx @@ -10,12 +10,10 @@ export default () => { return ( - isLoading + Show loading state - - Three projects are ready for review. - + Three items match your search. ); diff --git a/apps/docs/src/examples/loading-skeleton/provider.tsx b/apps/docs/src/examples/loading-skeleton/provider.tsx index b00e5ab4..abe6746b 100644 --- a/apps/docs/src/examples/loading-skeleton/provider.tsx +++ b/apps/docs/src/examples/loading-skeleton/provider.tsx @@ -16,7 +16,7 @@ export default () => { No local prop - Account balance: $1,240.00 + Three items match your search. @@ -24,7 +24,7 @@ export default () => { isLoading - Next payment: 21 August + Results updated a moment ago. @@ -32,7 +32,7 @@ export default () => { {'isLoading={false}'} - Visa ending in 4242 + Nothing else to show. diff --git a/apps/docs/src/examples/loading-spinner/basic.tsx b/apps/docs/src/examples/loading-spinner/basic.tsx index 01351c9e..99022de0 100644 --- a/apps/docs/src/examples/loading-spinner/basic.tsx +++ b/apps/docs/src/examples/loading-spinner/basic.tsx @@ -1,5 +1,5 @@ import { LoadingSpinner } from '@luke-ui/react/loading-spinner'; export default () => { - return ; + return ; }; diff --git a/apps/docs/src/examples/numeral/formats.tsx b/apps/docs/src/examples/numeral/formats.tsx index 08e0c2a7..9cfc1bb2 100644 --- a/apps/docs/src/examples/numeral/formats.tsx +++ b/apps/docs/src/examples/numeral/formats.tsx @@ -9,7 +9,7 @@ export default () => { Conversion rate: - Monthly spend: + Ticket price: Wind speed: diff --git a/apps/docs/src/examples/prose/basic.tsx b/apps/docs/src/examples/prose/basic.tsx index bef6a00d..9f942014 100644 --- a/apps/docs/src/examples/prose/basic.tsx +++ b/apps/docs/src/examples/prose/basic.tsx @@ -3,13 +3,16 @@ import { Prose } from '@luke-ui/react/prose'; export default () => { return ( -

Before you start

-

Make sure you have access to the project and its deployment environment.

-

Publish the release

+

Why structure matters

+

+ Headings break a page into sections a reader can scan, paragraphs group related sentences, + and lists set out steps or options one at a time. +

+

Reading a list

    -
  1. Tag the release.
    2. -
  2. Publish the packages.
    3. -
  3. Verify the deployment.
    4. +
  4. Scan the heading to see what the section covers.
    5. +
  5. Read the paragraph for context.
    6. +
  6. Follow the list for the details.
 ); diff --git a/apps/docs/src/examples/prose/lists.tsx b/apps/docs/src/examples/prose/lists.tsx index 230597f7..e21b571a 100644 --- a/apps/docs/src/examples/prose/lists.tsx +++ b/apps/docs/src/examples/prose/lists.tsx @@ -4,15 +4,15 @@ export default () => { return (
    -
  1. Prepare the release.
    2. +
  2. An ordered list numbers each item, so the order carries meaning.
  3. - Publish the packages. + An item can hold a nested list of its own.
      -
    • Publish dependencies first.
      • -
    • Publish the React package last.
      • +
    • A nested list is indented from its parent item.
      • +
    • An unordered list marks items with bullets instead of numbers.
    4. -
  4. Verify the release.
    5. +
  5. Spacing between items stays even at every level.
 ); diff --git a/apps/docs/src/examples/quote/basic.tsx b/apps/docs/src/examples/quote/basic.tsx index 949f645e..e49de79d 100644 --- a/apps/docs/src/examples/quote/basic.tsx +++ b/apps/docs/src/examples/quote/basic.tsx @@ -4,7 +4,7 @@ import { Text } from '@luke-ui/react/text'; export default () => { return ( - She described the interface as calm and clear. + A short phrase can appear as quoted material within a sentence. ); }; diff --git a/apps/docs/src/examples/strong/basic.tsx b/apps/docs/src/examples/strong/basic.tsx index a7d9029b..861048bf 100644 --- a/apps/docs/src/examples/strong/basic.tsx +++ b/apps/docs/src/examples/strong/basic.tsx @@ -4,7 +4,7 @@ import { Text } from '@luke-ui/react/text'; export default () => { return ( - Save your recovery code before continuing. + Read this part carefully before continuing. ); }; diff --git a/apps/docs/src/examples/text/lead.tsx b/apps/docs/src/examples/text/lead.tsx index c6d1ed76..6483e28c 100644 --- a/apps/docs/src/examples/text/lead.tsx +++ b/apps/docs/src/examples/text/lead.tsx @@ -1,5 +1,5 @@ import { Text } from '@luke-ui/react/text'; export default () => { - return Review your account details.; + return Lead text sits at a larger size than body text.; }; diff --git a/apps/docs/src/examples/text/transform.tsx b/apps/docs/src/examples/text/transform.tsx index 362b9f04..abdbe899 100644 --- a/apps/docs/src/examples/text/transform.tsx +++ b/apps/docs/src/examples/text/transform.tsx @@ -4,8 +4,8 @@ import { Text } from '@luke-ui/react/text'; export default () => { return ( - Project settings - View all activity + Uppercase text + Underlined text ); }; diff --git a/apps/docs/src/examples/text/truncation.tsx b/apps/docs/src/examples/text/truncation.tsx index 55274138..634dcfb5 100644 --- a/apps/docs/src/examples/text/truncation.tsx +++ b/apps/docs/src/examples/text/truncation.tsx @@ -5,10 +5,12 @@ export default () => { return ( - The weekly product update includes changes to reports, permissions, and saved views. + Short lines are easier to scan than long ones, which is why well-set text rarely stretches + edge to edge on a wide screen, no matter how much room is available. - The weekly product update includes changes to reports, permissions, and saved views. + Short lines are easier to scan than long ones, which is why well-set text rarely stretches + edge to edge on a wide screen, no matter how much room is available. ); diff --git a/docs/DOCUMENTATION.md b/docs/DOCUMENTATION.md index 201371e8..ecf23a0d 100644 --- a/docs/DOCUMENTATION.md +++ b/docs/DOCUMENTATION.md @@ -199,8 +199,21 @@ the code first. ### What to show -- Show one realistic thing a developer might write. Use values such as "Save changes" and - "you@example.com", never `foo`, `bar`, or lorem ipsum. +- Use content that makes the component or behaviour easy to understand. Do not introduce application + context that the example does not need. +- When content exists only so the component has something to render, prefer neutral or + self-referential copy, such as "Example checkbox" or "Example destination". +- Use application-specific content only when its meaning helps explain the component or behaviour. + "Save changes" can clarify a button action. An account or workspace does not clarify a checkbox + state. Avoid invented accounts, workspaces, billing details, characters, or other surrounding + application details. +- In comparison examples, content may name the value being demonstrated when the content is only a + specimen label, such as "Small", "Medium", and "Large". Keep those names in a caption beside the + control, not in the control's own label. +- Do not use API terms as labels for interactive controls. When the control's purpose is incidental, + use a neutral or self-referential label instead. +- When an example needs extended text, choose a subject that helps explain why the component + contains that structure. Do not invent an application scenario just to fill the example. - Let the example make the behaviour obvious. A reader should see what the section describes without hunting for it. - Keep the example as small as it can be without becoming artificial. @@ -208,8 +221,6 @@ the code first. result. - Do not demonstrate every value a prop accepts. Show the values a reader chooses between, and leave the full list to the Props page. -- Do not label example UI with prop names. A checkbox labelled "Invalid" documents the API. Label it - "Email me a receipt" instead. Exhaustive variant and state coverage belongs in the visual test kitchen sink, not in a docs example. See [TESTING.md](TESTING.md). -- 2.51.2