Motion fields
Five form fields that add movement without touching the accessibility contract: a focus lift, a slide in, a staggered fade, a spring pop and a help text that reveals on focus. The label stays associated with the control, help text stays in the aria-describedby chain even while hidden, and every animation gates on reduced motion.
Installation
The styled layer is free and installs like any other ai2 component.
Run the following command
npx shadcn@latest add @ai2/field-motionDependencies, the @ai2/tokens theme and the component file are installed together.
Install dependencies
npm install motionCopy the source
components/ui/field-motion.tsx"use client"
import * as React from "react"
import { AnimatePresence, motion, useReducedMotion } from "motion/react"
import { cn } from "@/lib/utils"
/* Motion field family: 5 form fields that share the same skeleton but each carry a
different motion (the label lifts on focus, slides while typing, fades while
typing, springs open, or the help text opens on focus). Accessibility does not
change: the label is bound to the control with htmlFor/id, the description is in
the aria-describedby chain, and invalidity falls back to the standard danger
appearance ON THE CONTROL via aria-invalid. All motion is disabled through
useReducedMotion; the final state is then shown instantly. The ids come from
useId. Color comes ONLY from tokens. Renders with no props too. */
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",
}
const controlBase =
"w-full rounded-md border border-field-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:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-danger aria-invalid:ring-danger/20 dark:aria-invalid:ring-danger/40"
const DEFAULT_LABEL = "Label"
const DEFAULT_DESCRIPTION = "Short help text for this field."
const DEFAULT_PLACEHOLDER = "Value"
const spring = { type: "spring" as const, stiffness: 420, damping: 30 }
interface FieldProps {
className?: string
size?: StyledSize
label?: React.ReactNode
description?: React.ReactNode
}
/* Paylasilan id kumesi. */
function useFieldIds(description: React.ReactNode) {
const base = React.useId()
const controlId = `${base}-control`
const descId = description != null && description !== false ? `${base}-desc` : undefined
return { controlId, descId }
}
function FieldLabel({
htmlFor,
size,
children,
className,
}: {
htmlFor: string
size: StyledSize
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}
</label>
)
}
function FieldDescription({ id, size, children, className }: { id?: string; size: StyledSize; children: React.ReactNode; className?: string }) {
if (children == null || children === false) return null
return (
<p id={id} data-slot="styled-field-description" className={cn("leading-snug text-muted-foreground", helpText[size], className)}>
{children}
</p>
)
}
/* Focus: when the control takes focus the label rises slightly and shifts to the primary tone. State is held at the top, not in the unmounting subtree. */
export function FocusField({ className, size = "md", label = DEFAULT_LABEL, description = DEFAULT_DESCRIPTION }: FieldProps) {
const { controlId, descId } = useFieldIds(description)
const reduce = useReducedMotion()
const [focused, setFocused] = React.useState(false)
return (
<div data-slot="styled-field" className={cn("flex w-full max-w-xs flex-col", gap[size], className)}>
<motion.div
animate={reduce ? {} : { y: focused ? -1 : 0 }}
transition={spring}
className="w-fit"
>
<FieldLabel htmlFor={controlId} size={size} className={cn("transition-colors", focused && "text-primary")}>
{label}
</FieldLabel>
</motion.div>
<input
id={controlId}
placeholder={DEFAULT_PLACEHOLDER}
aria-describedby={descId}
onFocus={() => setFocused(true)}
onBlur={() => setFocused(false)}
className={cn(controlBase, controlHeight[size])}
/>
<FieldDescription id={descId} size={size}>
{description}
</FieldDescription>
</div>
)
}
/* Slide: the field enters sliding from the left. No transform under reduced motion, fade only. */
export function SlideField({ className, size = "md", label = DEFAULT_LABEL, description = DEFAULT_DESCRIPTION }: FieldProps) {
const { controlId, descId } = useFieldIds(description)
const reduce = useReducedMotion()
return (
<motion.div
data-slot="styled-field"
initial={reduce ? { opacity: 0 } : { opacity: 0, x: -16 }}
animate={reduce ? { opacity: 1 } : { opacity: 1, x: 0 }}
transition={{ duration: 0.28, ease: "easeOut" }}
className={cn("flex w-full max-w-xs flex-col", gap[size], className)}
>
<FieldLabel htmlFor={controlId} size={size}>
{label}
</FieldLabel>
<input id={controlId} placeholder={DEFAULT_PLACEHOLDER} aria-describedby={descId} className={cn(controlBase, controlHeight[size])} />
<FieldDescription id={descId} size={size}>
{description}
</FieldDescription>
</motion.div>
)
}
/* Fade: parcalar sirayla solarak girer (etiket, kontrol, aciklama). */
export function FadeField({ className, size = "md", label = DEFAULT_LABEL, description = DEFAULT_DESCRIPTION }: FieldProps) {
const { controlId, descId } = useFieldIds(description)
const reduce = useReducedMotion()
const stagger = reduce ? 0 : 0.08
return (
<motion.div
data-slot="styled-field"
initial="hidden"
animate="shown"
variants={{ hidden: {}, shown: { transition: { staggerChildren: stagger } } }}
className={cn("flex w-full max-w-xs flex-col", gap[size], className)}
>
<motion.div variants={{ hidden: { opacity: 0 }, shown: { opacity: 1 } }} transition={{ duration: 0.25, ease: "easeOut" }} className="w-fit">
<FieldLabel htmlFor={controlId} size={size}>
{label}
</FieldLabel>
</motion.div>
<motion.input
id={controlId}
placeholder={DEFAULT_PLACEHOLDER}
aria-describedby={descId}
variants={{ hidden: { opacity: 0 }, shown: { opacity: 1 } }}
transition={{ duration: 0.25, ease: "easeOut" }}
className={cn(controlBase, controlHeight[size])}
/>
{description != null && description !== false ? (
<motion.p
id={descId}
data-slot="styled-field-description"
variants={{ hidden: { opacity: 0 }, shown: { opacity: 1 } }}
transition={{ duration: 0.25, ease: "easeOut" }}
className={cn("leading-snug text-muted-foreground", helpText[size])}
>
{description}
</motion.p>
) : null}
</motion.div>
)
}
/* Pop: the field enters growing with a spring. No scale under reduced motion, fade only. */
export function PopField({ className, size = "md", label = DEFAULT_LABEL, description = DEFAULT_DESCRIPTION }: FieldProps) {
const { controlId, descId } = useFieldIds(description)
const reduce = useReducedMotion()
return (
<motion.div
data-slot="styled-field"
initial={reduce ? { opacity: 0 } : { opacity: 0, scale: 0.94 }}
animate={reduce ? { opacity: 1 } : { opacity: 1, scale: 1 }}
transition={reduce ? { duration: 0.2, ease: "easeOut" } : spring}
className={cn("flex w-full max-w-xs flex-col origin-top", gap[size], className)}
>
<FieldLabel htmlFor={controlId} size={size}>
{label}
</FieldLabel>
<input id={controlId} placeholder={DEFAULT_PLACEHOLDER} aria-describedby={descId} className={cn(controlBase, controlHeight[size])} />
<FieldDescription id={descId} size={size}>
{description}
</FieldDescription>
</motion.div>
)
}
/* Reveal: the help text opens only on focus. An invisible copy stays in the DOM as sr-only so the text is always present and in aria-describedby. */
export function RevealField({ className, size = "md", label = DEFAULT_LABEL, description = DEFAULT_DESCRIPTION }: FieldProps) {
const base = React.useId()
const controlId = `${base}-control`
const hasDescription = description != null && description !== false
const descId = hasDescription ? `${base}-desc` : undefined
const reduce = useReducedMotion()
const [focused, setFocused] = React.useState(false)
return (
<div data-slot="styled-field" className={cn("flex w-full max-w-xs flex-col", gap[size], className)}>
<FieldLabel htmlFor={controlId} size={size}>
{label}
</FieldLabel>
<input
id={controlId}
placeholder={DEFAULT_PLACEHOLDER}
aria-describedby={descId}
onFocus={() => setFocused(true)}
onBlur={() => setFocused(false)}
className={cn(controlBase, controlHeight[size])}
/>
{hasDescription ? (
<>
<span id={descId} className="sr-only">
{description}
</span>
<AnimatePresence initial={false}>
{focused ? (
<motion.p
aria-hidden="true"
data-slot="styled-field-description"
initial={reduce ? { opacity: 0 } : { opacity: 0, height: 0 }}
animate={reduce ? { opacity: 1 } : { opacity: 1, height: "auto" }}
exit={reduce ? { opacity: 0 } : { opacity: 0, height: 0 }}
transition={{ duration: 0.2, ease: "easeOut" }}
className={cn("overflow-hidden leading-snug text-muted-foreground", helpText[size])}
>
{description}
</motion.p>
) : null}
</AnimatePresence>
</>
) : null}
</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.
Focus
The label lifts and takes the primary tone while the control has focus.
Short help text for this field.
import { FocusField } from "@/components/ui/field-motion"
<FocusField />Short help text for this field.
Short help text for this field.
Short help text for this field.
Short help text for this field.
Slide
The field slides in from the left as it mounts.
Short help text for this field.
import { SlideField } from "@/components/ui/field-motion"
<SlideField />Short help text for this field.
Short help text for this field.
Short help text for this field.
Short help text for this field.
Fade
Label, control and help text fade in one after another.
Short help text for this field.
import { FadeField } from "@/components/ui/field-motion"
<FadeField />Short help text for this field.
Short help text for this field.
Short help text for this field.
Short help text for this field.
Pop
A spring scales the field up into place.
Short help text for this field.
import { PopField } from "@/components/ui/field-motion"
<PopField />Short help text for this field.
Short help text for this field.
Short help text for this field.
Short help text for this field.
Reveal
The help text expands open only while the control has focus.
import { RevealField } from "@/components/ui/field-motion"
<RevealField />ai2 Motion fields: 5 styled variations on the token system
The ai2 Motion fields are a set of 5 decorative button variations from the styled layer of the @ai2 design system, built around entrance and focus motion on a form field. 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: framer-motion animates the entrance, the focus lift and the help text reveal. The styled layer is opt-in, so the dependency only lands if you use it; the base components stay lean. Under reduced motion, the transforms and height animations are skipped and the field appears in its final state.
What is in the ai2 Motion fields?
5 exports in one file: Focus, Slide, Fade, Pop and Reveal. 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: framer-motion animates the entrance, the focus lift and the help text reveal.
- Reduced-motion aware: Under prefers-reduced-motion, the transforms and height animations are skipped and the field appears in its final state.
- 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 Motion fields 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.