Update typography documentation: Enhance descriptions, add text scale section, and improve examples for consistency and clarity.

Author: 1aron

internal

@@ -81,7 +81,8 @@ export default function getValueCompletionItems(css: MasterCSS = createCSS(), ru
         if (eachDefinedRule.definition.key === ruleKey || eachDefinedRule.definition.subkey === ruleKey || eachDefinedRule.definition.aliasGroups?.includes(ruleKey)) {
             for (const variableName in eachDefinedRule.variables) {
                 if (completionItems.find(({ label }) => label === variableName)) continue
-                const variable = eachDefinedRule.variables[variableName]
+                const variable = eachDefinedRule.variables.get(variableName)
+                if (!variable) continue
                 const completionItem = generateVariableCompletionItem(variable, { scoped: true })
                 if (completionItem) {
                     completionItem.label = variableName

packages/language-service/src/utils/get-value-completion-items.ts

@@ -82,22 +82,12 @@ Change the text color of an element using the hexadecimal color code.
 ## Functions
 <Functions />
 
-### RGB color
-Change the text color of an element using the RGB color code.
+### rgb(), hsl(), oklch(), ...
+Change the text color of an element using color functions like `rgb()`, `hsl()`, `oklch()`, and others.
 <Demo>
     <div className="fg:rgb(23,95,233) font:56 font:heavy">Aa</div>
 </Demo>
 ```html
 <!-- @MARK fg:rgb(23,95,233) -->
 <p class="fg:rgb(23,95,233)">Aa</p>
-```
-
-### HSL color
-Change the text color of an element using the HSL color code.
-<Demo>
-    <div className="fg:hsl(219|83%|50%) font:56 font:heavy">Aa</div>
-</Demo>
-```html
-<!-- @MARK fg:hsl(219|83%|50%) -->
-<p class="fg:hsl(219|83%|50%)">Aa</p>
 ```

site/app/[locale]/guide/style-declarations/content.mdx

@@ -2,7 +2,7 @@ import buildingImg from '~/site/public/building.jpg';
 
 <Demo>
     <div className="bg:surface max-w:90x r:2x overflow:hidden s:demo outline:1|lightest">
-        <Image src={buildingImg} width="640" height="320" className="aspect:16/9 object:cover" />
+        <Image src={buildingImg} width="640" height="320" className="aspect:16/9 object:cover" alt="Typography" />
         <div className="p:6x">
             <div className="uppercase fg:sky font:semibold text:2xs tracking:widest mb:1x">Architectural</div>
             <div className="fg:strong font:medium text:md">Future-proof infrastructure</div>
@@ -11,11 +11,11 @@ import buildingImg from '~/site/public/building.jpg';
     </div>
 </Demo>
 ```html
-...
-<div class="uppercase font:semibold text:2xs tracking:widest ...">Architectural</div>
-<div class="font:medium text:md ...">Future-proof infrastructure</div>
-<div class="text:sm ...">
+…
+<div class="uppercase font:semibold text:2xs tracking:widest …">Architectural</div>
+<div class="font:medium text:md …">Future-proof infrastructure</div>
+<div class="text:sm …">
     From typography to spacing, every...
 </div>
-...
+…
 ```

site/app/[locale]/guide/typography/components/Overview.mdx

@@ -10,6 +10,7 @@ import FontFamilyBasicUsage from '../../reference/font-family/components/BasicUs
 
 ## Overview [sr-only]
 <Overview />
+The typography system in Master CSS provides a cohesive and scalable approach, [`text:<size>`](/guide/typography#text-scale), to setting text styles. It combines **font size**, **line height**, and **letter spacing** into unified tokens to ensure consistency and visual rhythm across interfaces—from fine print to large headlines.
 
 ### Namespaces for typography
 The typography system is built on a set of [variables](/guide/variables) that are organized into namespaces. This allows for easy customization and consistent application across your design.
@@ -22,6 +23,65 @@ The typography system is built on a set of [variables](/guide/variables) that ar
 
 ---
 
+## Text scale
+At its core, the system is powered by a semantic type scale (`text:3xs` to `text:10xl`) and corresponding font utilities (`font:*`, `line:*`, `tracking:*`) defined through design tokens. These values are carefully calibrated—not just mathematically scaled—to produce an optimal reading experience.
+
+Rather than manually composing multiple properties, you can use `text:<size>` to apply all three attributes—**font-size**, **line-height**, and **letter-spacing**—with a single class, tuned to the specific needs of each text scale.
+
+* `text:3xs ~ text:xs` — For fine print, annotations, captions, or table labels
+* `text:sm ~ text:lg` — Standard text sizes for body copy, paragraphs, and buttons
+* `text:xl ~ text:3xl` — Ideal for subheadings, lead paragraphs, or callouts
+* `text:4xl ~ text:10xl` — Reserved for large headings, page titles, and hero sections
+
+See some classic examples in the following sections. All examples use `text:<size>`, which automatically applies the ideal font size, line height, and letter spacing in a single utility.
+<BodyText />
+<Headings />
+<PageTitles />
+
+### Without vs With `text:<size>`
+Manually configuring typography often requires juggling multiple CSS properties like `font-size`, `line-height`, and `letter-spacing`. This can quickly become inconsistent, especially when reused across different components or pages.
+<Demo $py={0}>
+    <DemoPanel className="flex flex-col gap:8x w:full">
+        <div className="w:full">
+            <DemoLabel className="fg:crimson">font:5xl</DemoLabel>
+            <DemoP className="text:pretty font:5xl font:regular leading:1">Designing for consistency across every platform.</DemoP>
+        </div>
+        <div className="w:full">
+            <DemoLabel className="fg:beryl">text:5xl</DemoLabel>
+            <DemoP className="text:pretty text:5xl font:regular">Designing for consistency across every platform.</DemoP>
+        </div>
+    </DemoPanel>
+</Demo>
+Let’s compare a manual approach with the simplified `text:<size>` utility:
+
+(!) Manually add the most appropriate style for the title each time
+```html
+<h1 class="font:3xl tracking:-0.048rem leading:2.4rem">...</h1>
+```
+
+You may also find yourself tweaking these values individually for each heading or paragraph, which increases cognitive load and the risk of visual inconsistency.
+
+(o) Using `text:3xl` utility token
+```html
+<h1 class="text:3xl">...</h1>
+```
+
+The `text:lg` token applies a finely tuned combination of:
+
+<Class2CSS>{'text:3xl'}</Class2CSS>
+
+All values are calibrated to provide optimal readability and consistent rhythm across the type scale. No manual calculation, no guesswork—just a reliable, semantic shortcut.
+
+Why this matters? Using `text:<size>` ensures:
+
+* **Consistency** — every instance of `text:lg` looks exactly the same
+* **Maintainability** — no need to audit multiple values across stylesheets
+* **Scalability** — easier to theme or adjust from a central design token
+
+Whenever possible, prefer `text:<size>` over ad hoc styles. It’s faster, safer, and makes your typography systematically predictable.
+
+---
+
 ## Type scale
 The font scale ranges from `font:3xs` to `font:10xl`, with each size intentionally designed to deliver visual harmony and clear hierarchy across a variety of use cases.
 <FontSizeBasicUsage />
@@ -55,24 +115,3 @@ Our typography system defines a semantic range of font weight tokens, from `font
 
 ## Letter spacing
 <LetterSpacingBasicUsage />
-
----
-
-## Text scale
-However, when setting font size, you typically want to pair it with a corresponding line height. Smaller text sizes use taller line-heights to improve legibility, while larger sizes use tighter spacing to maintain compactness and strong hierarchy.
-
-In our [`text:<size>`](/reference/text-size) system, each size from `text:3xs` to `text:10xl` has a carefully adjusted line-height to achieve balanced readability and visual harmony. These values are not uniform ratios—they're intentionally tuned to suit the visual characteristics of each text scale.
-
-* `text:3xs ~ text:xs` Used for fine print, annotations, captions, or table labels
-* `text:sm ~ text:lg` Standard text sizes for body copy, paragraphs, and buttons
-* `text:xl ~ text:3xl` Ideal for subheadings, lead paragraphs, or callouts
-* `text:4xl ~ text:10xl` Reserved for large headings, page titles, and hero sections
-
-See some classic examples in the following sections.
-
-### Body text
-<BodyText />
-### Article headings
-<Headings />
-### Large titles
-<PageTitles />

site/app/[locale]/guide/typography/content.mdx

@@ -1,4 +1,4 @@
-Use the predefined [font size tokens](/reference/font-size) like `font:xs`, `font:sm`, and `font:md` to set the font size of an element.
+Use [font size tokens](/reference/font-size) like `font:xs`, `font:sm`, and `font:md` to set the font size of an element.
 <Demo $py={0}>
     <DemoPanel className="flex flex-col gap:8x w:full">
         <div className="w:full">

site/app/[locale]/reference/font-size/components/BasicUsage.mdx

@@ -3,11 +3,11 @@ Use tokens like `text:3xl` and `text:4xl` to style page titles and hero sections
     <DemoPanel className="flex flex-col gap:8x w:full">
         <div className="w:full">
             <DemoLabel>text:4xl</DemoLabel>
-            <DemoP className="text:pretty text:4xl">Designing for clarity and consistency across every platform.</DemoP>
+            <DemoP className="text:pretty text:4xl font:regular">Designing for clarity and consistency across every platform.</DemoP>
         </div>
         <div className="w:full">
             <DemoLabel>text:3xl</DemoLabel>
-            <DemoP className="text:pretty text:3xl">Designing for clarity and consistency across every platform.</DemoP>
+            <DemoP className="text:pretty text:3xl font:regular">Designing for clarity and consistency across every platform.</DemoP>
         </div>
     </DemoPanel>
 </Demo>

site/app/[locale]/reference/text-size/components/PageTitles.mdx

@@ -2,7 +2,7 @@ import define from 'internal/utils/metadata'
 
 const metadata = define({
     title: 'text-size',
-    description: 'Style utility for setting the font size and golden ratio line height for text.',
+    description: 'Style utility for setting optimally proportioned font size, line height and letter spacing all at once.',
     category: 'Syntax',
     type: 'entity',
     canIUseLink: 'https://caniuse.com/?search=font-size',