Styled field
Five form field wrappers: stacked, floating, inline, card and bordered. Each is sized, token-driven, wires up label, description, error and aria-describedby, and wraps any control.
Installation
The styled layer is free and installs like any other ai2 component.
Run the following command
npx shadcn@latest add @ai2/field-styledDependencies, the @ai2/tokens theme and the component file are installed together.
Copy the source
components/ui/field-styled.tsx"use client"
import * as React from "react"
import { cn } from "@/lib/utils"
/* Field family: 5 form-field wrappers. Each places a label + an optional
description + an optional error around a control (children) and associates them
with ids (useId + aria-describedby + aria-invalid are written onto the cloned
control). Color comes ONLY from tokens: the label is foreground, the description
muted-foreground, the error danger, and the required asterisk danger. A static
layout - no animation, framer is not needed. Renders with no props too (a default
label + description + a real <input placeholder="Value" />). */
export type StyledSize = "sm" | "md" | "lg" | "xl"
const gap: Record<StyledSize, string> = {
sm: "gap-1",
md: "gap-1.5",
lg: "gap-2",
xl: "gap-2.5",
}
const labelText: Record<StyledSize, string> = {
sm: "text-xs",
md: "text-sm",
lg: "text-sm",
xl: "text-base",
}
const helpText: Record<StyledSize, string> = {
sm: "text-xs",
md: "text-xs",
lg: "text-sm",
xl: "text-sm",
}
const controlHeight: Record<StyledSize, string> = {
sm: "h-8 text-sm",
md: "h-9 text-sm",
lg: "h-10 text-base",
xl: "h-12 text-base",
}
/* Tokenised input styling for the default control (when no children are given). */
function defaultControlClass(size: StyledSize, invalid: boolean) {
return cn(
"w-full rounded-md border bg-transparent px-3 py-1 text-foreground outline-none transition-colors placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50 focus-visible:ring-[3px]",
controlHeight[size],
invalid
? "border-danger focus-visible:border-danger focus-visible:ring-danger/25"
: "border-field-border focus-visible:border-ring focus-visible:ring-ring/50"
)
}
type BoundControlProps = {
id?: unknown
"aria-describedby"?: unknown
"aria-invalid"?: unknown
}
/* Clones the children (or the default input) and wires up id plus aria. */
function buildControl(
children: React.ReactNode,
size: StyledSize,
invalid: boolean,
ids: { controlId: string; describedBy?: string }
) {
const element = React.isValidElement(children)
? (children as React.ReactElement<BoundControlProps>)
: (<input placeholder="Value" className={defaultControlClass(size, invalid)} /> as React.ReactElement<BoundControlProps>)
const current = element.props
return React.cloneElement(element, {
id: current.id ?? ids.controlId,
"aria-describedby": ids.describedBy ?? current["aria-describedby"],
"aria-invalid": invalid ? true : current["aria-invalid"],
})
}
type FieldProps = {
className?: string
size?: StyledSize
label?: React.ReactNode
description?: React.ReactNode
error?: React.ReactNode
required?: boolean
children?: React.ReactNode
}
const DEFAULT_LABEL = "Label"
const DEFAULT_DESCRIPTION = "Short help text for this field."
/* Paylasilan id kumesi + describedby zinciri. */
function useFieldIds(description: React.ReactNode, error: React.ReactNode) {
const base = React.useId()
const controlId = `${base}-control`
const descId = description != null && description !== false ? `${base}-desc` : undefined
const errorId = error != null && error !== false ? `${base}-error` : undefined
const describedBy = [descId, errorId].filter(Boolean).join(" ") || undefined
return { controlId, descId, errorId, describedBy }
}
function FieldLabel({
htmlFor,
size,
required,
children,
className,
}: {
htmlFor: string
size: StyledSize
required?: boolean
children: React.ReactNode
className?: string
}) {
return (
<label
htmlFor={htmlFor}
data-slot="styled-field-label"
className={cn("w-fit font-medium leading-none text-foreground select-none", labelText[size], className)}
>
{children}
{required ? (
<span aria-hidden="true" className="ml-0.5 text-danger">
*
</span>
) : null}
</label>
)
}
function FieldMessages({
size,
descId,
description,
errorId,
error,
}: {
size: StyledSize
descId?: string
description: React.ReactNode
errorId?: string
error: React.ReactNode
}) {
return (
<>
{description != null && description !== false ? (
<p id={descId} data-slot="styled-field-description" className={cn("leading-snug text-muted-foreground", helpText[size])}>
{description}
</p>
) : null}
{error != null && error !== false ? (
<p id={errorId} data-slot="styled-field-error" className={cn("font-medium leading-snug text-danger", helpText[size])}>
{error}
</p>
) : null}
</>
)
}
/* Stacked: etiket ustte, kontrol, altta aciklama/hata - temiz varsayilan. */
export function StackedField({
className,
size = "md",
label = DEFAULT_LABEL,
description = DEFAULT_DESCRIPTION,
error,
required,
children,
}: FieldProps) {
const { controlId, descId, errorId, describedBy } = useFieldIds(description, error)
const control = buildControl(children, size, error != null && error !== false, { controlId, describedBy })
return (
<div data-slot="styled-field" className={cn("flex w-full max-w-xs flex-col", gap[size], className)}>
<FieldLabel htmlFor={controlId} size={size} required={required}>
{label}
</FieldLabel>
{control}
<FieldMessages size={size} descId={descId} description={description} errorId={errorId} error={error} />
</div>
)
}
/* Floating: the label sits on the top edge of the control (floating over the
border). */
export function FloatingField({
className,
size = "md",
label = DEFAULT_LABEL,
description = DEFAULT_DESCRIPTION,
error,
required,
children,
}: FieldProps) {
const { controlId, descId, errorId, describedBy } = useFieldIds(description, error)
const control = buildControl(children, size, error != null && error !== false, { controlId, describedBy })
return (
<div data-slot="styled-field" className={cn("flex w-full max-w-xs flex-col", gap[size], className)}>
<div className="relative">
<FieldLabel
htmlFor={controlId}
size={size}
required={required}
className="absolute -top-2 left-2.5 z-10 bg-background px-1 text-xs leading-none"
>
{label}
</FieldLabel>
{control}
</div>
<FieldMessages size={size} descId={descId} description={description} errorId={errorId} error={error} />
</div>
)
}
/* Inline: label on the left, control on the right, one row; messages below. */
export function InlineField({
className,
size = "md",
label = DEFAULT_LABEL,
description = DEFAULT_DESCRIPTION,
error,
required,
children,
}: FieldProps) {
const { controlId, descId, errorId, describedBy } = useFieldIds(description, error)
const control = buildControl(children, size, error != null && error !== false, { controlId, describedBy })
return (
<div data-slot="styled-field" className={cn("flex w-full max-w-md flex-col", gap[size], className)}>
<div className="flex items-center gap-3">
<FieldLabel htmlFor={controlId} size={size} required={required} className="shrink-0">
{label}
</FieldLabel>
<div className="min-w-0 flex-1">{control}</div>
</div>
<FieldMessages size={size} descId={descId} description={description} errorId={errorId} error={error} />
</div>
)
}
/* Card: tum alan token kart icinde, padding'li. */
export function CardField({
className,
size = "md",
label = DEFAULT_LABEL,
description = DEFAULT_DESCRIPTION,
error,
required,
children,
}: FieldProps) {
const { controlId, descId, errorId, describedBy } = useFieldIds(description, error)
const control = buildControl(children, size, error != null && error !== false, { controlId, describedBy })
return (
<div
data-slot="styled-field"
className={cn("flex w-full max-w-xs flex-col rounded-xl border border-border bg-card p-4 text-card-foreground", gap[size], className)}
>
<FieldLabel htmlFor={controlId} size={size} required={required}>
{label}
</FieldLabel>
{control}
<FieldMessages size={size} descId={descId} description={description} errorId={errorId} error={error} />
</div>
)
}
/* Bordered: sol tarafta token vurgu cizgisi; hata durumunda danger'a doner. */
export function BorderedField({
className,
size = "md",
label = DEFAULT_LABEL,
description = DEFAULT_DESCRIPTION,
error,
required,
children,
}: FieldProps) {
const invalid = error != null && error !== false
const { controlId, descId, errorId, describedBy } = useFieldIds(description, error)
const control = buildControl(children, size, invalid, { controlId, describedBy })
return (
<div
data-slot="styled-field"
className={cn(
"flex w-full max-w-xs flex-col border-l-2 pl-3",
invalid ? "border-danger" : "border-primary",
gap[size],
className
)}
>
<FieldLabel htmlFor={controlId} size={size} required={required}>
{label}
</FieldLabel>
{control}
<FieldMessages size={size} descId={descId} description={description} errorId={errorId} error={error} />
</div>
)
}Manual installs skip the @ai2/tokens theme, so add the token CSS from the theming guide or the tone colors will be missing.
Variations
5 takes on the same idea. Each is its own export, and every one accepts a size prop (sm, md, lg, xl) aligned to the base Button scale.
Stacked
Label on top, control, then description or error.
Short help text for this field.
import { StackedField } from "@/components/ui/field-styled"
<StackedField />Short help text for this field.
Short help text for this field.
Short help text for this field.
Short help text for this field.
Floating
A label straddling the control border.
Short help text for this field.
import { FloatingField } from "@/components/ui/field-styled"
<FloatingField />Short help text for this field.
Short help text for this field.
Short help text for this field.
Short help text for this field.
Inline
Label on the left, control on the right.
Short help text for this field.
import { InlineField } from "@/components/ui/field-styled"
<InlineField />Short help text for this field.
Short help text for this field.
Short help text for this field.
Short help text for this field.
Card
The field sits inside a token card.
Short help text for this field.
import { CardField } from "@/components/ui/field-styled"
<CardField />Short help text for this field.
Short help text for this field.
Short help text for this field.
Short help text for this field.
Bordered
A token left accent that turns danger on error.
Short help text for this field.
import { BorderedField } from "@/components/ui/field-styled"
<BorderedField />Short help text for this field.
Short help text for this field.
Short help text for this field.
Short help text for this field.
ai2 Styled field: 5 styled variations on the token system
The ai2 Styled field are a set of 5 decorative button variations from the styled layer of the @ai2 design system, built around form field layouts. They are free and MIT licensed, and every color comes from a semantic token, so they theme with the rest of ai2 in light and dark.
Motion runs on framer-motion: these are static layouts; no motion library work is required. The styled layer is opt-in, so the dependency only lands if you use it; the base components stay lean. Under reduced motion, there is no motion to reduce.
What is in the ai2 Styled field?
5 exports in one file: Stacked, Floating, Inline, Card and Bordered. Each renders a native button and takes a size prop (sm, md, lg, xl) aligned to the base Button. They are separate from the base Button on purpose: the base keeps its clean variant, tone and size axes, while the styled layer carries the effects.
You own the file. Copy the one category file and you have all 5 variations, with no runtime dependency on ai2 itself.
Why use it
- On-system by construction: Every color resolves to an ai2 semantic token, so the buttons follow your theme in light and dark with no extra work.
- Effect without the sprawl: The decorations live in a dedicated styled file, so the base Button keeps its clean, predictable API.
- Accessible and honest: Each renders a real button element, keeps a visible focus ring, and respects prefers-reduced-motion.
Features
- Token-driven color: No hardcoded hex or oklch; the look recolors with your theme tokens.
- framer-motion: these are static layouts; no motion library work is required.
- Reduced-motion aware: Under prefers-reduced-motion, there is no motion to reduce.
- Size aligned to the base: Every variation takes sm, md, lg and xl matching the base Button height scale, so styled and base buttons line up in a row.
Production tips
- Use it for emphasis, not everywhere: Styled buttons draw the eye. Reserve them for the one action you want people to take on a screen, and use the base Button for the rest.
- Keep labels as verbs: The decoration adds weight, so a clear action label keeps the button scannable.
- Pick one variation per surface: The variations share a family; using two different ones in the same view competes for attention.
Works with the rest of ai2
The Styled field sit alongside the base Button and the rest of the @ai2 registry. They share the same token file, so a styled action next to a base button or a badge stays visually consistent in both modes.