diff --git a/.changeset/docs-callouts.md b/.changeset/docs-callouts.md new file mode 100644 index 000000000..4e05fbc6c --- /dev/null +++ b/.changeset/docs-callouts.md @@ -0,0 +1,5 @@ +--- +"@tabler/docs": minor +--- + +Added `Info`, `Tip`, `Warning`, `Danger` and `Note` callouts, usable in any MDX page, with a reference page under Resources. diff --git a/docs/components/Callout.astro b/docs/components/Callout.astro new file mode 100644 index 000000000..05cf6d07d --- /dev/null +++ b/docs/components/Callout.astro @@ -0,0 +1,40 @@ +--- +// A tinted aside for a note, a tip or a warning inside docs prose. MDX pages use the +// named wrappers next to this file (, , , , ), which +// [...slug].astro passes to — so a page can call them without importing. +import Icon from '@ui/Icon.astro' + +export type CalloutType = 'info' | 'tip' | 'warning' | 'danger' | 'note' + +interface Props { + type?: CalloutType + /** Bold first line. Without it the callout is body text only. */ + title?: string | undefined +} + +const { type = 'info', title } = Astro.props + +const icons: Record = { + info: 'info-circle', + tip: 'bulb', + warning: 'alert-triangle', + danger: 'alert-circle', + note: 'pencil', +} + +const labels: Record = { + info: 'Info', + tip: 'Tip', + warning: 'Warning', + danger: 'Danger', + note: 'Note', +} +--- + + diff --git a/docs/components/callouts/Danger.astro b/docs/components/callouts/Danger.astro new file mode 100644 index 000000000..fddcb0be2 --- /dev/null +++ b/docs/components/callouts/Danger.astro @@ -0,0 +1,11 @@ +--- +import Callout from '../Callout.astro' + +interface Props { + title?: string | undefined +} +--- + + + + diff --git a/docs/components/callouts/Info.astro b/docs/components/callouts/Info.astro new file mode 100644 index 000000000..16b59786b --- /dev/null +++ b/docs/components/callouts/Info.astro @@ -0,0 +1,11 @@ +--- +import Callout from '../Callout.astro' + +interface Props { + title?: string | undefined +} +--- + + + + diff --git a/docs/components/callouts/Note.astro b/docs/components/callouts/Note.astro new file mode 100644 index 000000000..3275f2534 --- /dev/null +++ b/docs/components/callouts/Note.astro @@ -0,0 +1,11 @@ +--- +import Callout from '../Callout.astro' + +interface Props { + title?: string | undefined +} +--- + + + + diff --git a/docs/components/callouts/Tip.astro b/docs/components/callouts/Tip.astro new file mode 100644 index 000000000..f43e570f8 --- /dev/null +++ b/docs/components/callouts/Tip.astro @@ -0,0 +1,11 @@ +--- +import Callout from '../Callout.astro' + +interface Props { + title?: string | undefined +} +--- + + + + diff --git a/docs/components/callouts/Warning.astro b/docs/components/callouts/Warning.astro new file mode 100644 index 000000000..2250a1b28 --- /dev/null +++ b/docs/components/callouts/Warning.astro @@ -0,0 +1,11 @@ +--- +import Callout from '../Callout.astro' + +interface Props { + title?: string | undefined +} +--- + + + + diff --git a/docs/content/ui/components/map.mdx b/docs/content/ui/components/map.mdx index 3a36a0f78..99a0fe390 100644 --- a/docs/content/ui/components/map.mdx +++ b/docs/content/ui/components/map.mdx @@ -37,7 +37,9 @@ Then create a free account on [mapbox.com](https://www.mapbox.com/) and copy you mapboxgl.accessToken = 'pk.your-token-here' ``` -Use a public token only. A secret token (`sk.`) must never be sent to the browser. Limit the token to your own domains in the Mapbox dashboard. + + A secret token (`sk.`) must never be sent to the browser. Limit the token to your own domains in the Mapbox dashboard. + ## Usage diff --git a/docs/content/ui/getting-started/callouts.mdx b/docs/content/ui/getting-started/callouts.mdx new file mode 100644 index 000000000..3a6349d31 --- /dev/null +++ b/docs/content/ui/getting-started/callouts.mdx @@ -0,0 +1,88 @@ +--- +title: Docs callouts +summary: Callouts pull one sentence out of the flow of a page - a prerequisite, a gotcha, a warning. Tabler docs ship five of them, and any MDX page can use them without an import. +description: Info, Tip, Warning, Danger and Note callouts for Tabler documentation pages, with usage rules and accessibility notes. +--- + +## Overview + +A callout is a short aside inside a docs page. It carries something a reader must not miss while scanning: a step to do first, a mistake that costs an hour, a limit of the library. + +Callouts belong to the documentation, not to the Tabler UI package. For an alert inside a product interface, use the [alert component](/ui/components/alert) instead. + +## Variants + +Five variants cover what a docs page needs. The icon and the border carry the state color; the text stays body color, so a callout never depends on color alone. + +### Info + +Use it for context and prerequisites - something to know or to do before the rest of the page makes sense. + + + The examples on this page assume Tabler is already installed and the stylesheet is on the page. + + +```mdx + + The examples on this page assume Tabler is already installed. + +``` + +### Tip + +Use it for advice that makes the task easier, but is not required to finish it. + + + Some plugins keep the skin they were created with, so switching the theme afterwards has no effect. + + +### Warning + +Use it when missing the information breaks something later - a deprecation, a load order, a license limit. + + + It still compiles, but Dart Sass marks it as deprecated and will remove it in Sass 3.0. + + +### Danger + +Use it for what cannot be undone or what is unsafe - lost data, leaked credentials. + + + A secret token must never be sent to the browser. Limit the token to your own domains. + + +### Note + +A callout with no title is body text only. Use it for a short aside that needs no heading. + + + Tabler ships the compiled CSS in `dist/css`, so a project without a Sass pipeline can still use it. + + +## Usage + +Every MDX page in the docs can use the five tags without importing them - `docs/pages/[...slug].astro` passes them to the rendered content. + +```mdx + + Body text, with **markdown** and [links](/ui/getting-started/installation). + +``` + +The `title` prop is optional and renders as the first line in medium weight. The body is markdown, so keep it on its own lines inside the tags. + +## When to use one + +A callout works because it is rare. On a page where every third paragraph is boxed, nothing stands out and the reader skips all of them. + +- Use one when missing the information causes a real problem: a broken build, a security hole, a step done in the wrong order. +- Keep it to one or two per page. +- Do not box the main instruction of a section. If the paragraph is what the section is about, it belongs in the flow, under its heading. +- Do not box a list of accessibility rules or best practices. Those are lists, and they read better as lists. + +## Accessibility + +- Each callout renders as `