Skip to content
Permalink
Browse files

feat: design token and theme package documentation (#103)

* feat: design token and theme package documentation

* fix: address pull request feedback

* fix: more pr feedback and theme documentation

* fix: 3 to three

* feat: add in the composing with design tokens page

* fix: composition typos

* fix: typos and pr feedback for tokens docs

* chore: rebase on master

* docs(website): update design tokens package text

* chore(design-tokens): update package.json

* docs(website): theme package text changes

* docs(website): token composition text changes
  • Loading branch information...
SiTaggart committed Sep 27, 2019
1 parent c36e517 commit 30601132ccdec8f0fee79e0f293c80d0c0cff335
@@ -1,7 +1,7 @@
{
"name": "@twilio-paste/design-tokens",
"version": "2.4.0",
"description": "Design Tokens for the Paste Design System",
"description": "Paste Design System Tokens package with a number of different formats for Web, Mobile, and Sketch.",
"main": "dist/tokens.common.js",
"module": "dist/tokens.es6.js",
"types": "dist/tokens.common.d.ts",
@@ -1,7 +1,7 @@
{
"name": "@twilio-paste/theme",
"version": "0.4.1",
"description": "",
"description": "Paste Design System Theme Package which provides support for APIs to theme UIs and components.",
"author": "Twilio Inc.",
"license": "MIT",
"main:dev": "src/index.tsx",
@@ -108,6 +108,14 @@ module.exports = {
return 'PasteUtility';
}

if (node.relativePath.startsWith('paste-theme') && node.relativePath.endsWith('package.json')) {
return 'PasteThemePackage';
}

if (node.relativePath.startsWith('paste-design-tokens') && node.relativePath.endsWith('package.json')) {
return 'PasteDesignTokensPackage';
}

if (node.relativePath.endsWith('dist/tokens.gatsby.json')) {
return 'PasteTokenDefault';
}
@@ -46,6 +46,7 @@
"gatsby-transformer-remark": "^2.6.19",
"gatsby-transformer-sharp": "^2.2.6",
"lodash": "^4.17.15",
"pretty-format": "^24.9.0",
"prism-react-renderer": "^0.1.7",
"react": "^16.8.6",
"react-dom": "^16.8.6",
@@ -0,0 +1,21 @@
import * as React from 'react';
import {Box} from '@twilio-paste/box';
import {useTheme} from '@twilio-paste/theme';
import {Codeblock} from './codeblock';

// not typed correctly
const prettyFormat = require('pretty-format');

export const ThemeObjectDisplay: React.FC<{}> = () => {
const theme = useTheme();
const themeKeys = Object.keys(theme);
const reducedTheme = {};
themeKeys.forEach(key => {
reducedTheme[key] = {};
});
return (
<Box>
<Codeblock>{prettyFormat(reducedTheme)}</Codeblock>
</Box>
);
};
@@ -44,7 +44,7 @@ export type Language =

export interface CodeblockProps extends React.ComponentProps<'code'> {
children: string;
className: string;
className?: string;
live?: boolean;
}

@@ -8,16 +8,27 @@ import {P} from '../../Typography';
import {Heading} from '../../Heading';
import {getHumanizedNameFromPackageName} from '../../../utils/RouteUtils';

const getCategoryNameFromRoute = (categoryRoute: string): string => {
switch (categoryRoute) {
case SidebarCategoryRoutes.COMPONENTS:
return 'Components';
case SidebarCategoryRoutes.UTILITIES:
return 'Utilities';
case SidebarCategoryRoutes.TOKENS:
return 'Tokens';
default:
return 'Utilities';
}
};

const ComponentHeaderBasic: React.FC<{
name: string;
categoryRoute: typeof SidebarCategoryRoutes[keyof typeof SidebarCategoryRoutes];
}> = ({name, categoryRoute}) => (
<>
<Breadcrumb>
<BreadcrumbItem to="/">Home</BreadcrumbItem>
<BreadcrumbItem to={categoryRoute}>
{categoryRoute === SidebarCategoryRoutes.COMPONENTS ? 'Components' : 'Utilities'}
</BreadcrumbItem>
<BreadcrumbItem to={categoryRoute}>{getCategoryNameFromRoute(categoryRoute)}</BreadcrumbItem>
</Breadcrumb>
<Heading as="h1" headingStyle="headingStyle10">
{getHumanizedNameFromPackageName(name)}
@@ -73,10 +84,12 @@ const ComponentHeader: React.FC<ComponentHeaderProps> = ({name, categoryRoute, g
<ComponentHeaderBasic categoryRoute={categoryRoute} name={name} />
<P variant="lead">{description}</P>
<Box as="dl" mb="space100">
<Box mb="space20">
<PackageLabel>Status</PackageLabel>
<PackageValue>{status}</PackageValue>
</Box>
{status && (
<Box mb="space20">
<PackageLabel>Status</PackageLabel>
<PackageValue>{status}</PackageValue>
</Box>
)}
<Box mb="space20">
<PackageLabel>Version</PackageLabel>
<PackageValue>{version}</PackageValue>
@@ -86,6 +86,7 @@ const SidebarNavigation: React.FC<SidebarNavigationProps> = () => {
const [gettingStartedOpen, setgettingStartedOpen] = React.useState(
getCurrentPathname().includes(SidebarCategoryRoutes.GETTING_STARTED)
);
const [tokensOpen, setTokensOpen] = React.useState(getCurrentPathname().includes(SidebarCategoryRoutes.TOKENS));

return (
<SiteNav>
@@ -111,7 +112,28 @@ const SidebarNavigation: React.FC<SidebarNavigationProps> = () => {
</SiteNavNestList>
</SiteNavItem>
<SiteNavItem>
<SiteNavAnchor to="/tokens">Tokens</SiteNavAnchor>
<SiteNavButton onClick={() => setTokensOpen(!tokensOpen)} isOpen={tokensOpen}>
Design Tokens
<SiteNavAnchorArrow isOpen={tokensOpen} />
</SiteNavButton>
<SiteNavNestList isOpen={tokensOpen}>
<SiteNavItem>
<SiteNavAnchor to={SidebarCategoryRoutes.TOKENS}>Token list</SiteNavAnchor>
</SiteNavItem>
<SiteNavItem>
<SiteNavAnchor to={`${SidebarCategoryRoutes.TOKENS}/how-to-compose-custom-ui-with-tokens`}>
How to compose custom UI with tokens
</SiteNavAnchor>
</SiteNavItem>
<SiteNavItem>
<SiteNavAnchor to={`${SidebarCategoryRoutes.TOKENS}/design-tokens-package`}>
Design Tokens package
</SiteNavAnchor>
</SiteNavItem>
<SiteNavItem>
<SiteNavAnchor to={`${SidebarCategoryRoutes.TOKENS}/theme-package`}>Theme package</SiteNavAnchor>
</SiteNavItem>
</SiteNavNestList>
</SiteNavItem>
<SiteNavItem>
<SiteNavButton onClick={() => setComponentsOpen(!componentsOpen)} isOpen={componentsOpen}>
@@ -10,6 +10,7 @@ export const SidebarCategoryRoutes = {
PRIMITIVES: '/primitives',
UTILITIES: '/utilities',
GETTING_STARTED: '/getting-started',
TOKENS: '/tokens',
};

export const PackageStatus = {
@@ -0,0 +1,98 @@
---
title: Design Tokens Package
package: '@twilio-paste/design-tokens'
description: The Paste Design Tokens package allows you to install design tokens in a variety of different formats (Web, Mobile, Sketch, etc.)
---

import {graphql} from 'gatsby';
import {Box} from '@twilio-paste/box';
import Changelog from '@twilio-paste/design-tokens/CHANGELOG.md';
import {SidebarCategoryRoutes} from '../../constants';
import {Callout, CalloutTitle, CalloutText} from '../../components/callout';
import { Link } from "gatsby"



export const pageQuery = graphql`
{
allPasteDesignTokensPackage(filter: {name: {eq: "@twilio-paste/design-tokens"}}) {
edges {
node {
name
description
version
}
}
}
}
`;
<ComponentHeader
name="Design Tokens package"
categoryRoute={SidebarCategoryRoutes.TOKENS}
githubUrl="https://github.com/twilio-labs/paste/tree/master/packages/paste-core/components/button"
data={props.data.allPasteDesignTokensPackage.edges}
/>
***
<content>
The Paste design tokens are available as a NPM package which acts as the central source of truth for Paste. By using this package correctly, you can rely on a well-maintained, up-to-date definition of Twilio's Design Language. A simple way to grab or view the latest files in this package is to visit [UNPKG - @twilio-paste/design-tokens](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/).
## Supported Formats
<Callout>
<CalloutText>While the Paste Tokens Package supports the following formats, our roadmap <strong>currently prioritizes React Components and Sketch Libraries</strong> as primary deliverables of the Design System. Reach out to us at <em>#help-design-system</em> if you'd like to use Paste for another format: we'll help you out as much as we can!</CalloutText>
</Callout>
Paste Design Tokens are supported in the following formats within this package:
- [JSON](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/tokens.json)
- [Less](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/tokens.less)
- SCSS
- [as individual variables](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/tokens.default.scss)
- [as a SCSS map](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/tokens.map.scss)
- [CSS custom properties](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/tokens.custom-properties.css)
- [Android XML](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/tokens.android.xml)
- [iOS JSON](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/tokens.ios.json)
- JavaScript
- [commonJS](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/tokens.common.js)
- [es2015](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/tokens.es6.js)
- Typescript definitions
- [commonJS](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/tokens.common.d.ts)
- [es2015](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/tokens.es6.d.ts)
- [Sketch Palette](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/sketch.sketchpalette)
## Themes
Paste supports multiple themes. This is done by exporting the same token formats for each theme. Each file in the root of the design tokens package is exported for each theme with the corresponding values updated for each token. This allows different parts of Twilio to have their own visual styles whilst still maintaining a consistent Twilio feel, coherent component behavior, and preventing Design System bloat. Here's an example of Themes:
| Default theme | SendGrid theme |
|---------------------------------|---------------------------------|
| $color-brand-highlight: #F22F46 | $color-brand-highlight: #3368FA |
| $font-size-70: 1.5rem | $font-size-70: 1.75rem |
See our list of Tokens and their corresponding values in the <Link to="/tokens/">Token List</Link> page.
Within themes, we presently have support for:
- [Console (Default)](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/)
- [SendGrid](https://unpkg.com/browse/@twilio-paste/design-tokens/dist/themes/sendgrid/)
## Give us Feedback on this Page
As you use Paste, you'll likely encounter things that _don't seem right_. Please reach out with your feedback! Here's some prompts to consider:
- Is this page easy for me to consume?
- Is the information supporting it sufficient / well-described?
- What information is missing?
- How approachable is the documentation? Can a new engineer / PM / designer at Twilio get started with it easily?
***
<Box marginTop="space90">
<Changelog />
</Box>
</content>

1 comment on commit 3060113

@now

This comment has been minimized.

Please sign in to comment.
You can’t perform that action at this time.