Skip to content

Commit

Permalink
Merge pull request #76 from etchteam/feature/etch-545-better-spacing-…
Browse files Browse the repository at this point in the history
…docs

Feature/etch 545 better spacing docs
  • Loading branch information
mergify[bot] authored Aug 20, 2024
2 parents 88f7e05 + 74a0257 commit 84790a0
Show file tree
Hide file tree
Showing 24 changed files with 335 additions and 30 deletions.
20 changes: 19 additions & 1 deletion .eslintrc.cjs
Original file line number Diff line number Diff line change
@@ -1,7 +1,25 @@
module.exports = {
plugins: ['lit-a11y'],
plugins: ['lit-a11y', 'spellcheck'],
extends: ['@etchteam', 'plugin:lit-a11y/recommended'],
rules: {
'spellcheck/spell-checker': [
'warn',
{
lang: 'en_GB',
skipWords: [
'namespace',
'etchteam',
'plugins',
'lang',
'var',
'th',
'td',
'color',
'nowrap',
'center',
],
},
],
'@typescript-eslint/no-namespace': [
'error',
{
Expand Down
4 changes: 4 additions & 0 deletions .storybook/preview.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ import '../styles/base.css';
import '../styles/themes.css';
import '../styles/docs/docs.css';
import './styles.css'; // Storybook style overrides

import '../docs/components/Spacing';
import '../docs/components/TokenTable';

// @ts-ignore-next-line
import.meta.glob('../components/**/*.css', { eager: true });

Expand Down
5 changes: 3 additions & 2 deletions .storybook/styles.css
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,10 @@
}

docs-placeholder {
border: dotted 1px var(--diamond-theme-border-color-hover);
background: var(--diamond-color-grey-50);
border: dotted 1px var(--diamond-theme-border-color);
border-radius: var(--diamond-radius-sm);
display: block;
padding: var(--diamond-spacing-lg);
text-align: center;
text-align: left;
}
7 changes: 3 additions & 4 deletions components/canvas/Card/Card.stories.ts
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ export const Card: StoryObj = {
class="diamond-theme-${theme}"
>
<docs-placeholder>
<h2>Placeholder content</h2>
<h3>Placeholder content</h3>
<p>
The slot can contain anything, the card component acts as a simple
wrapper with optional props for styling the card itself.
Expand Down Expand Up @@ -105,17 +105,16 @@ export const ImageCard: StoryObj = {
render: () => html`
<diamond-wrap size="sm">
<diamond-card border radius shadow class="diamond-theme-light">
<diamond-img block responsive>
<diamond-img block responsive class="diamond-spacing-bottom-md">
<img
src="https://placehold.co/400x300"
alt="Placeholder"
width="400"
height="300"
class="diamond-spacing-bottom-md"
/>
</diamond-img>
<h3>Card title</h3>
<p>
<p class="diamond-spacing-bottom-lg">
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua.
</p>
Expand Down
7 changes: 7 additions & 0 deletions components/composition/Spacing/Spacing.stories.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,15 @@ import { html } from 'lit';
const description = `
Diamond spacing is a set of utility classes that can be added to any component or element.
The spacing class name format is \`diamond-spacing-{direction}-{size}\`, e.g. \`diamond-spacing-bottom-sm\`.
Spacing tweaks are one of the most common reasons for introducing page level CSS, which is
a slippery slope to a bloated CSS file. Diamond spacing reduces or eliminates these tweaks.
Individual components should not create spacing around themselves. Instead, they should use
spacing classes to create the desired layout.
It is generally recommended to use **bottom spacing** and **no top spacing** to prevent [margin collapse](https://www.joshwcomeau.com/css/rules-of-margin-collapse/).
`;

export default {
Expand Down
4 changes: 2 additions & 2 deletions docs/Theming.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Diamond UI supports component theming but provides no production-ready themes ou

All themes are based on a core set of variables.

<Source code={theme} language='css' />
<docs-token-table code={theme}></docs-token-table>

These can be overridden by setting the `:root` CSS variables to create a base theme and creating theme classes that can wrap components or groups of components.

Expand All @@ -23,7 +23,7 @@ Diamond UI optionally includes an example set of 3 basic themes: light, medium a

Components that support theming will apply the base theme tokens, such as setting the background to `--diamond-theme-background`.

<Source code={themes} language='css' />
<docs-token-table code={themes}></docs-token-table>

### Cards using demo themes

Expand Down
97 changes: 97 additions & 0 deletions docs/components/Spacing.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
import { LitElement, html, css } from 'lit';
import { customElement, property } from 'lit/decorators.js';

import { JSXCustomElement } from '../../types/jsx-custom-element';

export interface SpacingAttributes {
size: string;
}

@customElement('docs-spacing')
export class TokenTable extends LitElement {
@property({ reflect: true }) size: string = 'md';
@property({ reflect: true }) direction: 'top' | 'bottom' = 'bottom';
@property({ reflect: true }) alignment: 'center' | 'left' = 'center';

static readonly styles = css`
:host {
display: block;
color: var(--diamond-color-red-100);
font-size: var(--diamond-font-size-xs);
height: 0;
position: relative;
}
:host([direction='top']) .docs-spacing__content {
transform: translateY(-100%);
}
:host([alignment='left']) .docs-spacing__content {
justify-content: flex-start;
padding-left: var(--diamond-spacing-md);
}
.docs-spacing__content {
align-items: center;
display: flex;
gap: var(--diamond-spacing-xs);
height: var(--docs-spacing-height);
justify-content: center;
padding-left: var(--diamond-spacing-md);
}
.docs-spacing__border {
border-bottom: 1px solid var(--diamond-color-red-100);
border-top: 1px solid var(--diamond-color-red-100);
height: 100%;
position: relative;
width: 7px;
}
.docs-spacing__border::before {
background-color: var(--diamond-color-red-100);
content: '';
display: block;
height: 100%;
left: 50%;
position: absolute;
width: 1px;
}
.docs-spacing__text {
max-width: 0;
white-space: nowrap;
width: 0;
}
`;

render() {
const { size } = this;

return html`
<style>
:host {
--docs-spacing-height: var(--diamond-spacing-${size});
}
</style>
<div class="docs-spacing__content">
<div class="docs-spacing__border"></div>
<div class="docs-spacing__text">${size}</div>
</div>
`;
}
}

declare global {
interface HTMLElementTagNameMap {
'docs-spacing': SpacingAttributes;
}
}

declare module 'react' {
namespace JSX {
interface IntrinsicElements {
'docs-spacing': JSXCustomElement<SpacingAttributes>;
}
}
}
101 changes: 101 additions & 0 deletions docs/components/TokenTable.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
import { LitElement, html, css } from 'lit';
import { customElement, property } from 'lit/decorators.js';

import { JSXCustomElement } from '../../types/jsx-custom-element';

export interface TokenTableAttributes {
code: string;
}

@customElement('docs-token-table')
export class TokenTable extends LitElement {
@property({ reflect: true }) code: string;

static readonly styles = css`
:host {
display: block;
}
table {
border: var(--diamond-border);
border-collapse: collapse;
margin-block: var(--diamond-spacing-lg);
text-align: left;
width: 100%;
}
th,
td {
border: var(--diamond-border);
font-size: var(--diamond-font-size-sm);
padding: var(--diamond-spacing-sm);
}
th {
background-color: var(--diamond-color-grey-50);
}
code {
background-color: var(--diamond-color-grey-50);
border: var(--diamond-border);
border-radius: var(--diamond-radius-sm);
color: var(--diamond-color-grey-700);
font-size: var(--diamond-font-size-sm);
line-height: 1;
padding: var(--diamond-spacing-xs) var(--diamond-spacing-sm);
white-space: nowrap;
}
`;

render() {
const { code } = this;

// Find all the tokens in the code
const splitTokens = code.split(';');
const parsedTokens = splitTokens
.map((token) => /--diamond-([a-z]+)-([a-z-]+): (.+)/.exec(token))
.filter(Boolean)
.map((token) => ({
group: token?.[1],
name: token?.[2],
value: token?.[3],
}));

return html`
<table>
<thead>
<tr>
<th>Name</th>
<th>Token</th>
<th>Default value</th>
</tr>
</thead>
<tbody>
${parsedTokens.map(
(token) => html`
<tr>
<td>${token?.name}</td>
<td><code>--diamond-${token?.group}-${token?.name}</code></td>
<td>${token?.value}</td>
</tr>
`,
)}
</tbody>
</table>
`;
}
}

declare global {
interface HTMLElementTagNameMap {
'docs-token-table': TokenTableAttributes;
}
}

declare module 'react' {
namespace JSX {
interface IntrinsicElements {
'docs-token-table': JSXCustomElement<TokenTableAttributes>;
}
}
}
2 changes: 1 addition & 1 deletion docs/tokens/Border.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,6 @@ import * as ThemingStories from '../recipes/Theming.stories.ts'

Diamond borders inherit the colour from the theme style.

<Source code={code} language='css' />
<docs-token-table code={code}></docs-token-table>

<Canvas of={ThemingStories.Theming} />
2 changes: 1 addition & 1 deletion docs/tokens/Button.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import * as ButtonStories from '../../components/control/Button/Button.stories.t

# Button

<Source code={code} language='css' />
<docs-token-table code={code}></docs-token-table>

<Canvas of={ButtonStories.Button} />

Expand Down
2 changes: 1 addition & 1 deletion docs/tokens/Color.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import code from '../../styles/tokens/color.css?inline';

Diamond components are unbranded. Because of this, the colour palette is very limited to provide the minimum functionality and allow for easier white labelling.

<Source code={code} language='css' />
<docs-token-table code={code}></docs-token-table>

<diamond-grid class="diamond-spacing-bottom-lg" wrap="wrap">
{['white', 'black'].map((color) => (
Expand Down
2 changes: 1 addition & 1 deletion docs/tokens/Font.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import * as TypographyStories from '../recipes/Typography.stories.ts'

Diamond has font sizes from xs to xxxl and h1 to h4. If you end up past h4, that's often a bad sign.

<Source code={code} language='css' />
<docs-token-table code={code}></docs-token-table>

<Canvas of={TypographyStories.Headings} />

Expand Down
2 changes: 1 addition & 1 deletion docs/tokens/Input.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import * as RadioCheckboxStories from '../../components/control/RadioCheckbox/Ra

# Input

<Source code={code} language='css' />
<docs-token-table code={code}></docs-token-table>

<Canvas of={FormGroupStories.FormGroup} />

Expand Down
2 changes: 1 addition & 1 deletion docs/tokens/Label.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,6 @@ import * as FormGroupStories from '../../components/composition/FormGroup/FormGr

# Label

<Source code={code} language='css' />
<docs-token-table code={code}></docs-token-table>

<Canvas of={FormGroupStories.FormGroup} />
2 changes: 1 addition & 1 deletion docs/tokens/Radius.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import code from '../../styles/tokens/radius.css?inline';

There are 4 radii from xs to lg.

<Source code={code} language='css' />
<docs-token-table code={code}></docs-token-table>

<diamond-grid>
<diamond-grid-item small-mobile="6" tablet="3">
Expand Down
2 changes: 1 addition & 1 deletion docs/tokens/Shadow.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import code from '../../styles/tokens/shadow.css?inline';

Shadows can be used when an element sits on top of other elements, like a fixed nav bar.

<Source code={code} language='css' />
<docs-token-table code={code}></docs-token-table>

<diamond-wrap size="xs">
<diamond-card shadow radius border>
Expand Down
Loading

0 comments on commit 84790a0

Please sign in to comment.