Documenting with Astro/MDX

This guide explains how to document design decisions and tokens in your documentation using the built-in Astro components provided by the @noodlestan/designer-shows package.

Example:

<ShowDecision d="Brand Color Set" layout="column" size="xs" value="oklch" />
<ShowDecision d="Sizing Space Scale" layout="column" size="xs" />

oklch(62% 0.172 359deg)

oklch(71% 0.13 224deg)

oklch(17% 0 0deg)

oklch(97% 0 0deg)

32px

48px

72px

108px

Setup

Note

This guide is for @noodlestan/designer-shows/astro components and requires a working Astro website. You can create a website similar to this one using the Starlight theme in a matter of minutes.

Dependencies

The following packages are required:

• @noodlestan/designer-decisions
• @noodlestan/designer-functions
• @noodlestan/designer-integration-astro
• @noodlestan/designer-shows

npm install @noodlestan/designer-decisions @noodlestan/designer-functions \
  @noodlestan/designer-integration-astro \ @noodlestan/designer-shows

Configuring Designer Decisions

Create a directory to store your decision data and add a Designer Decisions configuration file in the root of your project.

• Directorydata/

  • …
• Directorysrc/

  • …
• astro.config.mjs
• dd.config.mjs
• package.json

The minimum required configuration specifies one or more DecisionSource from which to load decision data (DecisionInput).

dd.config.mjs

import { defineConfig } from '@noodlestan/designer-functions';

import { DEMO_DATA, SAMPLE_DATA } from '@noodlestan/designer-decisions';

export default defineConfig({
    store: {
        decisions: [SAMPLE_DATA, DEMO_DATA, './data'],
    },
});

In this example we configured the Designer Decisions Sample and Demo Data decision sources, as well as a local data/ directory for you to add more decisions.

Tip

Be sure to check the Loading and Validating guide for more options.

In the API / Configuration section you can find all configuration options and helpers.

Add the Astro Integration

What our Astro integration does:

• Connects our <Show*/> components to the decision store;
• Injecting Designer Decision styles into the page;
• Auto-refresh of the page when decision data changes;
• An entry point to configuring visualizations.

Add to your Astro config configuration, preferably after other integrations.

astro.config.mjs

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import designerDecisionsIntegration from '@noodlestan/designer-integration-astro';

export default defineConfig({
    ...
    integrations: [
        starlight({
            title: ...
            ...
        }),
        designerDecisionsIntegration(),
    ],
});

Note

If your Astro site is based on Starlight, like we do in our Astro Boilerplates, the designerDecisionsIntegration must be added after starlight() to make sure Designer Decisions customizations are applied.

Decision data

Create some decision files in your local ./data directory.

Tip

In the Models / Decision Types reference you will find sample data for each of the built-in decision models.

• Directorydata/

  • Directorydecisions/

    • color.json
    • space.json
    • …
• astro.config.mjs
• package.json

You can skip this step for now and use some of the decisions from the Sample and Demo Data sources.

Rendering decisions in MDX

Import the components you want to use and provide them with the decision name.

In this example we are using the <ShowDecision/> component to render both a ColorValueDecision and a ColorSetDecision, both from the DEMO_DATA source.

src/content/page.mdx

import { ShowDecision } from '@noodlestan/designer-shows/astro';

<ShowDecision d="Action Color" size="m" />
<ShowDecision d="Brand Color Set" layout="column" size="s" />

#9c2e5c

#d45084

#16b2dd

#0f0f0f

#f5f5f5

In the Astro integration docs you can find a comprehensive set of components for rendering decisions in different scenarios and layouts.

For instance, the <ShowDecisionCard/> component composes decision visualization, value, and details in a single layout.

src/content/page.mdx

import { ShowDecisionCard } from '@noodlestan/designer-shows/astro';

<ShowDecisionCard d="Action Color" />

Action Color

#9c2e5c

Used for buttons, links and navigation

For:

• Link Foreground
• Action Background
• Action Foreground
• Action Border
• Navigation Item Background

Not For:

• Non-interactive elements

Customizing value and visualization

All decision components expose common props that provide a high degree of control over how the decisions are rendered:

• value - hide or format the decision value
• viz - hide or configure the visualization
• options - visualization options passed down to the viz components (🚧 link)

Formatting the decision value

With some decision types, you may want to display their value in specific formats. The value prop is passed down to the specific decision component to control how the value is displayed.

For instance, the ShowColorValue components can display the color value in one or more color spaces.

<ShowDecision d="Action Color" value={['rgb', 'oklch']} size="m" />

#9c2e5c

oklch(48% 0.15 359deg)

Hiding the decision value

In this example we are hiding the decision value and rendering its visualization under a custom label.

<label>Brand Blue</label>
<ShowDecision d="Brand Blue" value={false} size="l" />

Brand Blue

Choosing a different visualization

Some decision types can be rendered using different visualizations.

The viz prop is passed down to value components to determine which visualization is used.

For instance, the ShowSpaceViz component can represent a space value with a few different shapes.

<ShowDecision d="Avatar Minimum Size" viz="circle" />
<ShowDecision d="Card Thumb Minimum Size" viz="square" />

50px

175px

Configuring visualization options

(🚧 links)

Some visualization primitives expose also an options prop.

In this example we are rendering the same color decision using two different modes: fg and bg.

In both cases we are providing a contrast color. We also set the custom content for the first one, and switch to text mode on the second.

<ShowDecision ... viz="fg" options={{ contrast: '#000000', content: 'Hello' }} />
<ShowDecision ... viz="bg" options={{ contrast: '#FFFFFF', mode: 'text' }} />

Hello

Leaves rustled quietly. Clouds parted. The tall grass swayed lazily, whispering secrets only the wind could hear. A cold wind carried the scent of rain and something else—something unfamiliar. He hesitated, the key heavy in his palm, its purpose still unclear. The fire crackled softly, a fleeting comfort against the encroaching chill. A lantern swung from the hunter’s hand, casting long, jagged shadows on the trees. The fox paused at the edge of the clearing, its golden eyes reflecting the pale glow of the moon as it surveyed the silent expanse. The door creaked open, revealing a covered in dust, filled with forgotten things. The moonlight spilled through the treetops, illuminating a forgotten glade where ancient stones bore inscriptions long worn by time. At the heart of the forest, where the trees grew taller and closer, a feeling of profound stillness settled, as if time had slowed. The night seemed endless, a tapestry of sounds and shadows, each thread a fragment of a story waiting to be discovered. A low growl came from the darkness, closer than expected. The sun rose magnificently, announcing a brand new day. They exchanged a glance, unspoken understanding passing between them. In her hand, she held the map, edges frayed, its markings barely legible in the dim light. Somewhere deep within the woods, the faint hum of a hidden stream could be heard, weaving its way through roots and stones like a lifeline. From the shadows, a new beginning emerged. The horizon shimmered, painted in hues of orange and pink. The old bridge creaked under the weight of footsteps, threatening to give way. A new path appeared from nowhere. Beneath the starry canopy, the air was thick with mystery, the scent of moss and pine mingling with the crispness of the night. The quick brown fox darted through the underbrush, its ears pricked for danger. Overhead, the stars shimmered like a riddle waiting to be solved. A twig snapped in two. A single feather floated to the ground, its edges glinting with an iridescent sheen. The river hummed a tune, weaving a silver thread through the forest. The forest seemed alive, each rustle and whisper carrying secrets of ages past, guarded by time itself. A pair of squirrels ran for cover while the fox wrestled the wind. A clock chimed in the distance, its sound eerily out of place. An old wooden gate creaked in protest as it opened to an unfamiliar visitor. The brushes on the side of the road stood by, in expectation. The lantern flickered twice. The hunter's breath was visible in the cold night air, his steps deliberate and measured as he followed the faint trail left behind. An owl took off. The fox ran. The moon broke through the clouds, revealing a path that had not been there before. Beneath the stars, the now world seemed boundless and impossibly quiet. Somewhere in the distance, an owl hooted, its cry echoing in the still night.

Hiding the visualization

In this example we are hiding the visualization and rendering its value next to a custom label.

RGB: <ShowDecision d="Brand Pink" viz={false} value="hsl" />

#d45084

RGB

See also

• Examples
• Boilerplates / Astro/Starlight
• Integrations / Astro
• API / configuration