--- name: link-usage description: > Use after component-usage-ux when an app needs the low-level @techsio/ui-kit Link atom for inline or unstyled navigation, including external links and framework adapter usage. metadata: component_version: "1.3.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux framework-consumer-integration ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "" contributor_sources: "libs/ui/src/atoms/link.tsx libs/ui/src/atoms/link-button.tsx libs/ui/src/atoms/link.figma.ts" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit Link Usage Use Link for inline navigation or when a molecule needs a framework-agnostic link. Use LinkButton when the link should look like a button. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `Link`. **Use it when** - Navigation inside text, lists, tables (record names), breadcrumbs and footers. **Use something else when** | Need | Use instead | | --- | --- | | Navigation styled as a button | LinkButton | | An action | Button | **Do** - Make link text describe the destination; in tables, link the record name, not a separate `View` column. - Mark external links and links that download files. - Keep underline or another non-colour cue for links inside text. **Don't** - Use links for actions (`Delete`). - Make whole cards clickable while also nesting other links inside. **Copy and states** - Destination-first, sentence case; no `here`. **Behaviour (from the UX spec)** - A Link only navigates; it never changes data or silently drops an unsaved draft. - Link has no disabled or visited state in code. For an unavailable destination render text (or a disabled `LinkButton`); visited styling, if an app adds it, never means done or approved. - Only the page that actually loads is current; opening a panel or a navigation branch is not navigation. **Figma → code** | Figma | Code | | --- | --- | | `state=disabled` | no prop; plain text or `LinkButton disabled` | | `state=visited` | no style in the kit | | `state=hover` / `active` | not props (browser states) | | — | `size="sm" \| "md" \| "lg" \| "current"`, `external` | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Atoms/Link → UX guidelines*. ## Setup ```tsx import NextLink from "next/link" import { Link } from "@techsio/ui-kit/atoms/link" Terms ``` Supported props: ```text as: React element type external: boolean href and other props from the chosen element/component ``` ## Core Patterns ### Use external for off-site links ```tsx External docs ``` `external` sets safe target/rel defaults unless they are explicitly supplied. ### Use NextLink in Next apps ```tsx Account ``` Default to the framework link adapter in Next apps. ### Escalate styled CTA to LinkButton ```tsx Checkout ``` Do not build button visual styling on top of Link. ## Common Mistakes ### HIGH Native anchor for normal app link Wrong: ```tsx Account ``` Correct: ```tsx Account ``` Source: libs/ui/src/atoms/link.tsx ### HIGH Link styled as button Wrong: ```tsx Checkout ``` Correct: ```tsx Checkout ``` Source: libs/ui/src/atoms/link-button.tsx ### MEDIUM External link without external prop Wrong: ```tsx Vendor ``` Correct: ```tsx Vendor ``` Source: libs/ui/src/atoms/link.tsx ### MEDIUM Custom framework wrapper Wrong: ```tsx const AppLink = (props: Props) => ``` Correct: ```tsx Blog ``` ## Validation Commands ```sh rg -n "]*className=.*(bg-|px-|py-|rounded-)" apps rg -P -n "]*href=\"https?://(?![^>]*external)" apps rg -n "function .*Link|const .*Link" apps rg -n "