Skip to content

Add example page components, and let a wide example use its width - #233

Open
jwrosewell wants to merge 8 commits into
mainfrom
feature/examples-editor-component
Open

Add example page components, and let a wide example use its width#233
jwrosewell wants to merge 8 commits into
mainfrom
feature/examples-editor-component

Conversation

@jwrosewell

@jwrosewell jwrosewell commented Sep 2, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What this adds

Eight components for example pages, in three partials under
pattern-library/source/sass/06-examples, and nothing outside that folder
changes.

Class What it is for
c-eg-editor A multi line box a reader types a structured document into
c-eg-control An input, a select or a button inside an example, all one size
c-eg-controls A row of controls that wraps, with its label
c-eg-fields A table of properties a reader sets, aligned on the middle
c-eg-pre and --wrap Output printed exactly as something produced it
c-eg-result with __label, __value, __note and --none The answer an example gives, shown large enough to read across a desk
c-eg-intro The notes a page opens with, laid across the width
c-eg-masthead The logo beside the title rather than above it

c-eg-page--wide also changes, in 00-page.scss. It was widening the page
to 1400px and then holding every paragraph inside it at the 800px reading
measure, so a page that asked for the width still ran its prose down the
left hand half and left the right hand half empty. Nothing inside it is
narrowed any more. The reading measure now comes from c-eg-intro and
c-eg-columns dividing the width, which keeps a readable column without
leaving half the page unused.

Why

An example that takes input from a reader had nothing in the design system
to build with, so it either used form components meant for something else
or carried its own CSS. The derived property script
tester was carrying its
own, which is exactly the drift this design system exists to stop.

Composing the existing pieces was tried first and is not enough. A textarea
taking b-input and c-eg-value gets the input chrome and the code face,
but none of the room to work in, and it was worse to type into than the
hand written styles it replaced.

What the components do

Each one reuses the existing mixins rather than restating them, so an
example control sits beside a b-input in the same form without looking
like a different control. What they add is only what the existing
components have no reason to carry.

  • The editor has a minimum height, because one opening a line tall is
    unusable, a vertical only resize grip, because widening one editor in a
    two column layout pushes the other out of the grid, a two space tab stop,
    because the formats these examples show are indented two spaces, and
    lines that scroll sideways rather than wrap, because wrapping a
    structured format hides the indentation that carries its meaning.
  • The controls are one size and one height whether they are an input, a
    select or a button, so a row of them reads as a row rather than as three
    sizes of thing.
  • The fields table aligns each row on its middle. Aligned on the top,
    a row whose label wraps to two lines leaves its input sitting high, which
    reads as a mistake.
  • The result panel is the one thing on the page a reader came for, so
    it is set at the top of the type scale with the label and the note around
    it much smaller. --none is for an example that has no answer to give.

Written generally rather than for the one page that needs them today, in
the way 07-status.scss was.

Checked

Built with npm run build:css after every commit and the output compared
class by class against the previously built examples-main.min.css.
Nothing was lost at any step, and every addition is one of the classes in
the table above.

The rule order matters and is right. make-input() sets Arial and
make-text-code() follows it, so the editor ends up monospace. The nested
icon rule resolves to .b-form-group--with-icon .c-eg-editor, correctly
scoped rather than applying to every editor.

Consumer

The derived property tester uses all of them, with the built stylesheet
vendored beside the page in the way the device detection and IP
intelligence example apps vendor it. That copy is refreshed from this
branch and will be taken again once this merges.

The page is worth opening while reviewing this, because every component
here is on it: https://51degrees.github.io/derived-properties/

@jwrosewell
Add an editor component to the examples design system
ac6939c 
An example that lets a reader type something structured and see what it
does needs a multi line box, and there was no component for one, so the
derived property script tester had been styling its own.

c-eg-editor reuses the design system input chrome and the documentation
code face rather than restating either, so an editor sits beside a
b-input in the same form without looking like a different control. What
it adds is only what a single line input has no reason to carry.

  A minimum height, because an editor opening one line tall is unusable
  and every example using one wants the same starting size.

  A vertical only resize grip. Widening one editor in a two column
  layout would push the other out of the grid.

  A two space tab stop, because the formats these examples show are
  indented two spaces and a tab jumping eight columns makes pasted
  content look wrong.

  Lines that scroll sideways rather than wrap. Wrapping a structured
  format hides the indentation that carries its meaning.

Written generally rather than for the one page that needs it today, in
the way the status component was.
@github-actions

github-actions Bot commented Sep 2, 2026

Copy link
Copy Markdown
Contributor

Documentation preview 👀

@jwrosewell
Give the editor rounded corners, a code line height and a focus ring
e8483c1 
Three things a multi line editor needs that the first version left out.

Rounded corners using $rounded, matching every other rounded surface.

A line height of 1.5. make-input sets 1.2, which is right for one line of
prose and too tight for many lines of indented code.

A focus ring on focus-visible, because an editor is where a reader is
typing and which box holds the caret has to be obvious. A keyboard user
gets the ring and a pointer user clicking into the box does not.

The border softens to $colour-grey-light so the box reads as an area to
work in rather than as a bordered rectangle.
@jwrosewell
Give examples a wider shell and controls a reader can use
8e1af34 
Three additions, from building an example that takes input.

c-eg-page--wide widens the shell to 1400px. 800px is a comfortable
measure for reading a column of prose, which is what nearly every example
is, and it is far too narrow once a page puts two columns or a table of
controls inside it, because the columns halve it and every control in
them collapses and truncates. Prose keeps the 800px measure rather than
stretching with it.

c-eg-control is a single line box or list. It asks for a minimum width,
which is the part that was missing, because a control in a narrow table
column otherwise collapses to the column and truncates what it holds.

c-eg-controls lays out a row of things that belong together, such as a
label, a list and the button that acts on it. c-eg-button-row sets
margins and nothing else, which is all a row of buttons needs, and it
leaves a control filling the line with the button underneath.

08-editor.scss becomes 08-fields.scss and holds all three, since the
editor and the control share one treatment, now extracted as
make-example-field.

The gap is general rather than specific to one page. Almost every example
we ship reports data and asks for nothing, so the system grew a rich set
of ways to display a result and nothing for a reader to type into.
@jwrosewell jwrosewell changed the title Add an editor component to the examples design system Give examples a wider shell, and fields a reader can type into Sep 2, 2026
@jwrosewell
Make a table of example fields read as one size
e070d89 
A row of fields held three sizes, because the system sizes each piece for
where it usually appears. A control carries the body size it needs
standing alone in a form, the code face is a step smaller because it
usually sits inside running prose, and cell text is neither. Put all
three in one row and a reader sees three different things.

c-eg-fields makes everything inside it take the size of the table, and
drops the control back to the cell padding, because a row of controls is
dense by nature and padding sized for a lone box makes the table tall for
no reason.
@jwrosewell
Align a field row on its middle rather than its top
01fe719 
A table aligns to the top, which is right where a cell holds a paragraph
and the row is as tall as the longest one. In a field table the tall
cells are controls, which centre what they hold, so a name aligned to the
top sits above the control beside it and nothing in the row lines up.
@jwrosewell
Add a block for output printed exactly as something produced it
737c6a8 
An example that prints a message or a canonical form was using a bare
pre, and a long line inside one widens its container. On a page laid out
in columns that pushes everything else out of shape, which is worse than
a scrollbar.

c-eg-pre scrolls sideways instead and carries the code face and the same
soft background as the fields, so printed output reads as part of the
same set.

c-eg-pre--wrap is for output that is prose rather than structure, such as
a message. Prose is easier to read wrapped and something with meaningful
indentation is not, which is why it is a choice rather than the default.
@jwrosewell
Add a result panel for the answer an example gives
0dd4ae4 
An example computes one thing and everything else on its page explains
that one thing, so the answer is what a reader looks for first and comes
back to after every change. Reported at the size of ordinary body text it
reads as one more paragraph among the paragraphs explaining it.

c-eg-result is a panel for that answer, with a quiet label, the value in
the code face at a size that makes it the first thing seen, and a quiet
note underneath for how to read it. The modifier carries the case where
there is no answer, because there is no value to colour and a reader
scanning for one needs to see at a glance that there is not one.

Put it above whatever a reader changes rather than below, so that
changing something and seeing what it did takes no scrolling.
@jwrosewell
Let an example use the width it asked for
8c31207 
A wide example page kept every paragraph at the 800px reading measure,
so a page that asked for 1400px because it has two columns and a table
of controls in it still ran its prose down the left hand half and left
the right hand half empty. The measure is worth keeping, but keeping it
by narrowing one paragraph at a time wastes the room the page asked for.

The measure now comes from dividing the width rather than from leaving
it unused. c-eg-intro lays the notes an example opens with across two
columns from md and three from xl, so what a page has to say before it
starts takes one band and the example itself is on screen without
scrolling, and each column is still a readable width. c-eg-masthead puts
the logo beside the title and the lead rather than above them, which
gives back the height of the logo.

Nothing inside c-eg-page--wide is narrowed any more, so an example that
puts something wide in the page gets the width without having to
override a rule from here.
@jwrosewell jwrosewell changed the title Give examples a wider shell, and fields a reader can type into Add example page components, and let a wide example use its width Sep 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@jwrosewell