fix(ui): align form labels and grouped surfaces

Author: kev1n77

design-system/apps/design-lab/src/pages/PatternsPage.tsx

@@ -35,7 +35,7 @@ import {
   type TokenOverrides,
 } from "@openbitfun/ui";
 import { useI18n, type MessageKey } from "../i18n";
-import { NestedMenuPattern, ProviderConfigurationPattern, SceneToolbarPattern } from "./ReferencePatterns";
+import { FormTypographyPattern, NestedMenuPattern, ProviderConfigurationPattern, SceneToolbarPattern } from "./ReferencePatterns";
 
 interface PatternsPageProps {
   colorScheme: ColorScheme;
@@ -116,6 +116,8 @@ export function PatternsPage({ colorScheme, contrast, density, tokenOverrides }:
           </Card>
         </PatternSection>
 
+        <FormTypographyPattern />
+
         <PatternSection description={t("patterns.navigation.description")} index="02" title={t("patterns.navigation.title")}>
           <div className="pattern-navigation-stage" data-openbitfun-pattern="navigation-panel">
             <NavigationPanel

design-system/apps/design-lab/src/pages/ReferencePatterns.tsx

@@ -8,6 +8,7 @@ import {
   Field,
   FieldGroup,
   FieldRow,
+  FormSection,
   Icon,
   IconButton,
   Input,
@@ -35,6 +36,26 @@ import {
 } from "@openbitfun/ui";
 import { useI18n } from "../i18n";
 
+export function FormTypographyPattern() {
+  const { t } = useI18n();
+  return <Card appearance="subtle" padding="md" data-openbitfun-pattern="form-typography">
+    <FormSection title={t("patterns.settings.title")} description={t("patterns.settings.description")}>
+      <FieldGroup>
+        <FieldRow>
+          <Field label={t("patterns.settings.language")} description={t("patterns.settings.languageDescription")} orientation="horizontal" controlWidth="fill" labelWidth="md">
+            <Input defaultValue="English / 简体中文 / 繁體中文" />
+          </Field>
+        </FieldRow>
+        <FieldRow>
+          <Field label={t("patterns.provider.headers")} description={t("components.preview.fieldDescription")} orientation="vertical" controlWidth="fill">
+            <Input defaultValue="X-OpenBitFun-Workspace-Display-Name-With-A-Long-Value" />
+          </Field>
+        </FieldRow>
+      </FieldGroup>
+    </FormSection>
+  </Card>;
+}
+
 export function ProviderConfigurationPattern() {
   const { t } = useI18n();
   const [open, setOpen] = useState(false);

design-system/packages/design-tokens/src/system.tokens.json

@@ -169,6 +169,14 @@
         "letterSpacing": { "$value": "{letterSpacing.normal}" }
       }
     },
+    "fieldHelper": {
+      "$description": "Field helper leading: 16px at the default 11px type size, scaling with user typography.",
+      "lineHeight": { "$type": "number", "$value": 1.4545454545454546 }
+    },
+    "formDescription": {
+      "$description": "Form-section description leading: 16px at the default 13px type size, scaling with user typography.",
+      "lineHeight": { "$type": "number", "$value": 1.2307692307692308 }
+    },
     "support": {
       "fontFamily": { "$value": "{font.family.control}" },
       "fontSize": { "$value": "{font.size.meta}" },

design-system/packages/theme-openbitfun/README.md

@@ -62,7 +62,8 @@ component token is absent, and keeps explicit component overrides intact.
 
 - `color.surface.scene`, `panel`, and `raised` own primary content and elevated planes.
 - `color.surface.chrome` owns persistent application structure such as navigation and window-control regions.
-- `color.surface.tertiary` is an opaque low-emphasis fill for persistent grouped content such as cards and field groups.
+- `color.surface.tertiary` is an opaque low-emphasis fill for persistent containers such as cards.
+- `color.field.groupBackground` owns grouped form surfaces: light mode uses a 3% black tint so the underlying surface remains visible; dark and high-contrast modes retain their tertiary fill. Opaque tertiary containers and transient `surface.subtle` feedback cannot express this form-specific contract. Imported appearances inherit an explicitly supplied legacy tertiary color unless they supply the new field token.
 - `color.surface.subtle` is a translucent local tint for transient feedback and small inset details. It must not define a persistent application plane.
 - `color.selection.surface` owns persistent neutral selection. Hover and pressed colors remain action feedback and are not substitutes for selection.
 - `color.codeChange.added` (`#1aa73e`) and `color.codeChange.removed` (`#ec221f`) also anchor success and danger emphasis. Warning emphasis uses `#ff8c00`; information uses the existing creative-action blue (`#2e7eff`). These clear hues share light tints instead of separate per-component palettes.

design-system/packages/theme-openbitfun/src/dark.tokens.json

@@ -175,6 +175,7 @@
       }
     },
     "field": {
+      "groupBackground": { "$description": "Grouped form tint; independent of opaque tertiary containers and transient subtle feedback.", "$type": "color", "$value": "{color.surface.tertiary}" },
       "borderActive": { "$type": "color", "$value": "{color.field.borderFocus}" },
       "placeholder": { "$type": "color", "$value": "{color.content.muted}" },
       "background": { "$type": "color", "$value": "{ref.color.neutral.900}" },

design-system/packages/theme-openbitfun/src/high-contrast-dark.tokens.json

@@ -51,6 +51,7 @@
       }
     },
     "field": {
+      "groupBackground": { "$description": "Grouped form tint; independent of opaque tertiary containers and transient subtle feedback.", "$type": "color", "$value": "{color.surface.tertiary}" },
       "borderActive": { "$type": "color", "$value": "{color.field.borderFocus}" },
       "placeholder": { "$type": "color", "$value": "{color.content.muted}" },
       "border": { "$type": "color", "$value": "{ref.color.gray.250}" },

design-system/packages/theme-openbitfun/src/high-contrast-light.tokens.json

@@ -51,6 +51,7 @@
       }
     },
     "field": {
+      "groupBackground": { "$description": "Grouped form tint; independent of opaque tertiary containers and transient subtle feedback.", "$type": "color", "$value": "{color.surface.tertiary}" },
       "borderActive": { "$type": "color", "$value": "{color.field.borderFocus}" },
       "placeholder": { "$type": "color", "$value": "{color.content.muted}" },
       "border": { "$type": "color", "$value": "{ref.color.gray.650}" },

design-system/packages/theme-openbitfun/src/light.tokens.json

@@ -175,6 +175,7 @@
       }
     },
     "field": {
+      "groupBackground": { "$description": "Grouped form tint; independent of opaque tertiary containers and transient subtle feedback.", "$type": "color", "$value": "rgba(0, 0, 0, 0.03)" },
       "borderActive": { "$description": "Input and SearchField editing border, distinct from the stronger generic focus indicator used by other controls.", "$type": "color", "$value": "{color.field.borderHover}" },
       "placeholder": { "$description": "Empty field hints and decorative adornments; distinct from general secondary prose.", "$type": "color", "$value": "rgba(0, 0, 0, 0.40)" },
       "background": { "$type": "color", "$value": "{ref.color.neutral.0}" },

design-system/packages/ui/README.md

@@ -397,3 +397,11 @@ Tool-specific data shaping, localization, host actions, stores, and heavy
 renderers remain in the consuming product and enter through semantic props,
 callbacks, and slots. Bespoke product workflows remain product-owned rather
 than being forced into a standard package view.
+
+Field labels follow their orientation: horizontal labels use the 13px semibold
+label role, while vertical labels use the 11px regular meta role. Field helpers
+use secondary content with 16px leading at the default 11px font size;
+FormSection descriptions use primary content with 16px leading at 13px. Both
+leading roles scale with user typography. FieldGroup uses the form group tint,
+retaining its existing row padding, dividers, and radius. The Patterns form
+specimen shows both orientations and long values over a tinted container.

design-system/packages/ui/src/components/Field/Field.meta.ts

@@ -23,7 +23,7 @@ export const fieldMeta = {
   tokens: [
     "color.content.requiredIndicator",
     "color.content.primary",
-    "color.content.muted",
+    "color.content.secondary",
     "color.status.danger.content",
     "layout.field.rootGap",
     "layout.field.horizontalGap",
@@ -35,7 +35,9 @@ export const fieldMeta = {
     "layout.field.labelGap",
     "layout.field.labelActionGap",
     "layout.field.controlGap",
-    "type.label.md.fontSize",
+    "type.label.selected.fontSize",
+    "type.meta.fontSize",
+    "type.fieldHelper.lineHeight",
     "type.support.fontSize",
   ],
 } as const satisfies ComponentMeta;