Awesome

Bruck is a lo-fi prototyping system made with web components. Quickly create and comment on interface layouts. The output is screen reader accessible, and responsive without you having to author breakpoints.

Try out the demo

Warning: Bruck is experimental, and in its very early stages of development.

Get started

1. Clone this repository.
2. (No npm install because there's no dependencies, unless you want to contribute — then you may need the Jest stuff)
3. Write HTML with the help of the components (below) in the index.html and split-screen editor.html files. Check out a demo in demo.html.
4. Serve by using something like http-server at the root
5. That's pretty much it. Requests and contribution offers welcome.

Documentation

(Used in conjunction with the utility classes.)

• Components
  • <t-ext>
  • <w-ords>
  • <i-mage>
  • <c-enter>
  • <b-ox>
  • <s-tack>
  • <g-rid>
  • <c-luster>
  • <s-pread>
  • <s-idebar>
  • <l-ine>
  • <i-con>
  • <p-rogress>
  • <d-rawer>
  • <s-creen>
  • <g-o>
  • <f-low>
  • <c-omment>
  • <c-lone>
  • <i-nput>
  • <t-extarea>
  • <s-elect>
  • <c-heckbox>
  • <r-adios>
  • <o-utput> (see Working with data)
  • <m-odel> (see Working with data)
• Utility classes
• Working with data
• Actions

Components

<t-ext>

The <t-ext> component lets you generate a paragraph of dummy text. Each word is represented as a line. 'Words' wrap like any other text content.

Props

Example

<t-ext words="50,75"></t-ext>

Accessibility information

Just the lorem ipsum text underlying the emblematic line-words.

<w-ords>

The <w-ords> component lets you generate sets of words, picked at random from lorem ipsum. It is an inline element, so can be used to generate text inside a <p> or <h2> etc.

Props

Example

The following will produce a paragraph or 3-4 sentences.

<p>
  <w-ords sentence repeat="3,4"></w-ords>
</p>

Accessibility information

Just the lorem ipsum text verbatim.

<i-mage>

The <i-mage> element creates an accessible dummy/placeholder image (with a X-through style generated via Houdini's Paint API). The available horizontal space is filled unless minWidth and maxWidth props are supplied.

Props

Example

<i-mage ratio="3:4"></i-mage>

Accessibility information

"Image with [ratio] aspect ratio".

<b-ox>

The simplest of components: just wraps some content with some padding, and a border if you want it.

Props

Example

<b-ox pad="2" border>
  <h3>My box</h3>
  <t-ext></t-ext>
</b-ox>

Accessibility information

"['Bordered'?] box containing [# of child elements] elements"

<s-tack>

The <s-tack> component lets you inject whitespace between flow elements. Wrap it around a set of elements and separate them visually. Critically, it accepts a repeat prop that lets you multiply its contents a set number of times.

Props

Example

<s-tack repeat="3">
  <t-ext></t-ext>
</s-tack>

Accessibility information

"Column of [# of child elements] elements"

<g-rid>

The <g-rid> element let's you easily compose a responsive grid using CSS's Grid algorithm. Like <s-tack> it lets you repeat the contents/children you supply. Useful for quickly mocking up a set of card components or similar.

Props

Example

<g-rid repeat="10">
  <b-ox border>
    <h2>Card title</h2>
    <t-ext words="25,50"></t-ext>
  </b-ox>
</g-rid>

Accessibility information

"Grid of [# of child elements] elements, each [itemWidth] wide"

<c-luster>

The <c-luster> component uses Flexbox to let you cluster items around the horizontal center of their context. Items wrap where there is no room for them all on one line, maintaining responsiveness.

Props

Example

<c-luster align="bottom">
  <div>Will Something on the left</div>
  <div>Something in the center</div>
  <div>something on the right</div>
</c-luster>

Accessibility information

"Set of [# of child elements] centrally grouped elements"

<s-pread>

The <s-pread> component uses Flexbox to let you separate items horizontally. Items wrap where there is no room for them all on one line, maintaining responsiveness.

Props

Example

<s-pread gap="2">
  <div>Will be pushed to the left</div>
  <div>Will appear in the center</div>
  <div>Will be pushed to the right</div>
</s-pread>

<s-idebar>

The <s-idebar> component wraps two child elements, with one as the designated 'sidebar' and the other taking up the remaining space. If more than two child elements are supplied, construction ceases and an error is returned.

The designated sidebar only appears as a sidebar where it is narrower than its sibling. Otherwise, Flexbox reorganizes the two elements into a single column (uses the flex-grow: 999 hack).

Props

Example

Creates a sidebar of the second element (introduced with the <h2> heading). The gap between the sidebar and the adjacent content matches the second point on the modular scale (one point higher than the default).

<s-idebar to="right" gap="2">
  <div>
    <h1>The main content</h1>
    <!-- etc -->
  </div>
  <div>
    <h2>The sidebar content</h2>
    <!-- etc -->
  </div>
</s-idebar>

Accessibility information

"Content with a [left || right] sidebar"

<l-ine>

The <l-ine> component configures child elements inline, with the option to add a separator. The separator can be any character or HTML.

Props

Example

<l-ine gap="2">
  <a href="#index">Home</a>
  <a href="#about">About</a>
  <a href="#faq">FAQ</a>
</l-ine>

Accessibility information

"Line of [# of child elements] elements"

<i-con>

The <i-con> component inserts an inline SVG icon, by name, from the icons folder (using fetch). The size of the icon is determined by its parent's font-size, or you can use the u-h1 — u-h6 utility classes on the <i-con> itself.

Props

Example

<i-con name="tick" label="Correct!"></i-con>

Accessibility information

None by default (it is assumed the icon will be accompanied by text). Or you can supply a label via the label prop. This will also include the img ARIA role.

<p-rogress>

The <p-rogress> component displays a series of steps in a continuum to indicate how far along the user is in a process.

Props

Example

<p-rogress steps="address,payment details,confirmation" current="confirmation"></p-rogress>

Accessibility information

"Progress indicator of [# of steps] steps" (in addition to list semantics and aria-current).

<c-enter>

The <c-enter> component simply creates a centralized column (with horizontal margins set to auto). The max-width is set to the --measure custom property value (under css/lib/variables.css) by default.

Props

Example

<c-enter>
  <s-tack gap="2">
    <h2>A centrally aligned document section</h2>
    <s-tack repeat="5">
      <t-ext></t-ext>
    </s-tack>
  </s-tack>
</c-enter>

Accessibility information

NA

<d-rawer>

A basic collapsible section, as you might find in an accordion. The first child (light DOM) element is use to form a button. This is wrapped in a heading, for which the level can be adjusted using the level prop.

Props

Example

<d-rawer>
  <any-element>Collapsible section title</any-element>
  <p>This content appears when the handle is clicked...</p>
  <p>...and so does this content.</p>
</d-rawer>

Accessibility information

"Collapsible section"

<s-creen>

The <s-creen> element lets you define whole screens (like those defined within a routed Single Page Application). You can link between screens using either the <g-o> call-to-action component, or regular links pointing to hash fragments that match the screens' ids.

The <s-creen> with the index id is displayed on page load.

Props

Example

<s-creen id="index">
  <h1>The default screen</h1>
  <g-o to="about">About</g-o>
</s-creen>
<s-creen id="about">
  <h1>The about screen</h1>
  <a href="#index">Home</a>
</s-creen>

Accessibility information

The value of the <code>label</code> prop (or the <code>id</code> value as a fallback).

<g-o>

A call-to-action type component, specifically for linking between <s-creen> elements.

Props

Example

<g-o to="index">Home</g-o>

Accessibility information

The text content of the link.

<f-low>

The <f-low> component lets you group elements as a navigable sequence of steps, such as sections in a form. On hover and focus, previous and next buttons are exposed to change steps.

Props

Methods

Example

<f-low>
  <s-tack>
    <h2>Step 1</h2>
    <t-ext></t-ext>
  </s-tack>
  <s-tack>
    <h2>Step 2</h2>
    <t-ext></t-ext>
  </s-tack>
  <s-tack>
    <h2>Step 3</h2>
    <t-ext></t-ext>
  </s-tack>
</f-low>

Accessibility information

"Sequence of [# of child elements] steps"

<c-omment>

Allows you to write a comment for any part of the interface, simply by wrapping it and supplying text for the wording prop. The comment is revealed by pressing a '?' button that is revealed on both hover and focus.

Props

Example

<c-omment wording="A set of card components">
  <g-rid repeat="10">
    <div>
      <h2>Card title</h2>
      <t-ext words="25,50"></t-ext>
    </div>
  </g-rid>
</c-omment>

Accessibility information

The comment wrapper is identified as a region. The buttons to open and close the comment are suitably labeled.

<c-lone>

The <c-lone> lets you instantiate content from a named <template>. It's the easiest way to reuse compound components.

Props

Example

<template id="image-and-text">
  <i-mage maxWidth="20rem" ratio="6:9"></i-mage>
  <t-ext words="20,40"></t-ext>
</template>

<c-lone of="image-and-text"></c-lone>

Accessibility information

NA (whatever the cloned elements provide)

<i-nput>

The <i-nput> component is an abstraction of a basic type="text" input/label, with accessible labeling built in.

Props

Example

<i-nput name="favoriteAnimal" label="Your favorite animal"></i-nput>

Accessibility information

Standard <label> and <input> elements are used (and associated with one another) and convey the standard/expected semantics to assistive technologies.

<t-extarea>

The <t-extarea> component is an abstraction of a basic <textarea> with accessible labeling built in.

Props

Example

<t-extarea name="favoriteAnimal" label="Tell us about your favorite animal"></t-extarea>

Accessibility information

Standard <label> and <textarea> elements are used (and associated with one another) and convey the standard/expected semantics to assistive technologies.

<s-elect>

The <s-elect> component is an abstraction of a basic <select>/<option>s pattern, with accessible labeling built in.

Props

Example

<s-elect label="Your favorite animal" name="favoriteAnimal" options="dog, cat, fish, aardvark" selected="aardvark"></s-elect>

Accessibility information

Standard <label> and <select> elements are used (and associated with one another) and convey the standard/expected semantics to assistive technologies.

<c-heckbox>

The <c-heckbox> component is an abstraction of a basic type="checkbox" input/label, with accessible labeling built in.

Props

Example

<c-heckbox name="likesAnimals" label="Do you like animals?" checked></c-heckbox>

Accessibility information

Standard <label> and <input> elements are used (and associated with one another) and convey the standard/expected semantics to assistive technologies.

<r-adios>

The <r-adios> component is an abstraction of a basic radio group pattern (using <fieldset> and <legend> for the group labeling).

Props

Example

<r-adios label="Your favorite animal" name="favoriteAnimal" options="dog, cat, fish, aardvark" checked="aardvark"></r-adios>

Accessibility information

Standard <fieldset>, <legend>, <label>, <input> and <select> elements are used (and associated with one another) and convey the standard/expected semantics to assistive technologies.

Utility classes

A set of utility classes for global styling. Each is prefixed with u-.

u-invert

With class="u-invert" a CSS filter inverts the colors of the element in hand.

u-text-center, u-text-left, u-text-right

For realigning text.

u-h1, u-h2, u-h3, u-h4, u-h5, u-h6

For emulating the font sizes of semantic headings without introducing heading elements (mapped to h1—h6 sizes).

u-rounded

Rounds the edges of an element with a 50% border radius (making square elements circles).

Working with data

Sometimes you'll want to work with dummy text (like <w-ords> and <t-ext>). Other times, you'll want to add real content using basic elements like <h2> and <p>. But you can also work with data.

The data.js file

This file defines a global data object and is found in the root of the /js folder. You can add properties to the data object as you wish. For example, I might add a people property defining an array of usernames:

// in js/data.js
export default {
  people: [
    {
      firstName: 'Lara',
      lastName: 'Hogan'
    },
    {
      firstName: 'Hulk',
      lastName: 'Hogan'
    },
    {
      firstName: 'Paul',
      lastName: 'Hogan'
    },
    {
      firstName: 'Heydon',
      lastName: 'Pickering'
    }
  ]
}

Using the <o-utput> component, you can template the data. Note that this refers to the property identified using the mandatory property attribute (property="people" here).

<o-utput property="people">
  <b-ox>
    <g-rid>
      {{% for (let name in this) { %}}
      <s-tack>
        <i-mage ratio="5:9"></i-mage>
        <h3 class="u-text-center">{{% this[name].lastName %}}, {{% this[name].firstName %}}</h3>
        {{% this[name].firstName === 'Heydon' ? '(me!)' : '' %}}
      </s-tack>
      {{% } %}}
    </g-rid>
  </b-ox>
</o-utput>

There you have it: a set of user 'cards' laid out in a <g-rid>.

The <m-odel> component

The <m-odel> component wraps a form and lets you change or add data to the global data object. It too takes a property attribute (i.e. it can only affect one property at a time, and only works to one level of depth).

<m-odel property="people">
  <form>
    <s-tack>
      <i-nput label="First name" name="firstName"></i-nput>
      <i-nput label="Last name" name="lastName"></i-nput>
      <button type="submit">Submit</button>
    </s-tack>
  </form>
</m-odel>

When the submit button is pressed, a FormData object of values is created based on the form fields' name attributes. In this case, the object would be:

{
  firstName: /* value from `name="firstName"` */,
  lastName: /* value from `name="lastName"` */
}

If the window.data.people property's value is an object, it will be overridden with the new data. If it is an array, the data will be pushed as a new item (as in the people example). If the <m-odel> contains just one field, the FormData object will be flattened into a simple string of that single value. That is:

// This would be avoided...
people: [
  {
    person: 'Heydon Pickering'
  }
]

// ...in preference of this:

people: [
  'Heydon Pickering'
]

(Note: In this scenario, the field's name attribute would actually be immaterial because the first and only property of the FormData object is taken, whatever it is called.)

Whenever a <m-odel> changes the data, a 'stored' event is fired, alerting any <o-utput> elements of the new data so they can rerender accordingly. This event also fires on page load, rendering out the original data.

Security

Be careful not to allow the use of <m-odel> or the creation of <o-utput> on domains that expose personal/sensitive data. You may invite XSS.

Actions

A set of global functions to be used with inline handlers (onClick etc). It is recommended these are used primarily on <button> elements, since they are accessible. Each action is prefixed with the actions namespace, like onClick="actions.nameOfAction(arg1, arg2)".

show(id)

Shows an element by its id (removes the hidden property).

Example

Shows the element with the id 'myElem':

<button onClick="action.show('myElem')">SHow the element</button>

hide(id)

Hides an element by its id (adds the hidden property).

Example

Hides the element with the id 'myElem':

<button onClick="action.hide('myElem')">SHow the element</button>

showHide(id)

Toggles the visibility of an element by its id (toggles the hidden property).

Example

Toggles the visibility of the element with the id 'myElem':

<button onClick="action.showHide('myElem')">SHow the element</button>

flowPrev(this)

Shows the previous element/slide/step within a <f-low> component. Must be called from inside the <f-low> component, with this as the only argument.

Example

<button onClick="action.flowPrev(this)">Previous</button>

flowNext(this)

Shows the next element/slide/step within a <f-low> component. Must be called from inside the <f-low> component, with this as the only argument.

Example

<button onClick="action.flowNext(this)">Previous</button>

flowGoTo(this, index)

Shows the next element/slide/step within a <f-low> component. Must be called from inside the <f-low> component, with this as the first argument. The second argument is the index of the element/slide/step (not zero-based; the first item is 1).

Example

Shows the third element/slide/step within the <f-low>.

<button onClick="action.flowGoTo(this, 3)">Previous</button>