0
Fork 0
mirror of https://github.com/TryGhost/Ghost.git synced 2025-02-03 23:00:14 -05:00

Added basic documentation to Admin Design System

refs. https://github.com/TryGhost/Team/issues/3150
This commit is contained in:
Peter Zimon 2023-05-22 12:09:34 +02:00
parent a6e534bba8
commit e4cac91e19
4 changed files with 114 additions and 11 deletions

View file

@ -0,0 +1,41 @@
import { Meta } from '@storybook/blocks';
<Meta title="About" />
<style>
{`
.sb-doc {
max-width: 720px;
width: 100%;
font-family: Inter, sans-serif !important;
margin: 0 auto;
}
.sb-highlight {
background: yellow;
border-radius: 7px;
padding: 12px 24px;
margin: 0;
}
`}
</style>
<div className="sb-doc">
# AdminX Design System
This is a documentation of the design system of Ghost AdminX.
## Why?
The purpose of any design system is to bring order to chaos and this is not any diffrent here either. Historically we maintained consistency in the Ghost Admin via using components and global CSS as much as possible. However due to the growth of the product and the loose system, more and more exotic patterns and styles emerged—which resulted in inconsistency.
The main goal of the design system (any design system) is to bring order into chaos by defining and documenting **reusable components**.
## Install
ATM the design system is part of the AdminX Settings project but soon it will be decoupled with the intention to be able to (re)use it in any future React based Admin projects. Eventually it should be an independent package that could be added to any React app.
`yarn add @tryghost/admin-x-ds`
</div>

View file

@ -0,0 +1,73 @@
import { Meta } from '@storybook/blocks';
import SBStructure from './assets/ds-structure.png';
<Meta title="Development" />
<style>
{`
.sb-doc {
max-width: 720px;
width: 100%;
font-family: Inter, sans-serif !important;
margin: 0 auto;
}
.sb-highlight {
background: #E4D2FF;
border-radius: 7px;
padding: 12px 24px;
margin: 0 0 24px;
}
`}
</style>
<div className="sb-doc">
# Development
Here's a guideline of how new components should be developed to match the goal of the design system.
<br />
## Structure
The design system contains **reusable components**. These components live in one of the following groups:
### Global
Contains common components that are used across all parts (in all apps) of the admin: buttons, checkboxes, lists, input fields etc—the usual suspects. You can check them in the "Global" group in the sidebar.
### App specific
The Admin is broken down to multiple React apps, each with its own set custom of reusable components. **These components are also part of the design system** which allows potential reusability in the future, and forces designers and developers to think in terms of the design system.
### What about non-reusable components?
With all fairness, **most of the components should be part of the design system**. Of course there pages, containers etc. in each app which are obviously **non-reusable**, however these should be built up of _mostly_ reusable components.
<p className='sb-highlight'>If you can't decide whether a component is reusable or not, then default to adding it to the design system!</p>
<br />
<img src={SBStructure} />
<br /><br />
### Example: settings app
[TBD: Settings structure]
<br />
## How to develop new components?
If there's a single thing you should remember is this:
<p className='sb-highlight'>Storybook is **the central tool** of the design system, it is **not** an afterthought. It is the **starting point** of the development of any new component.</p>
### Steps to develop new components
[TBD: expand]
1. Create the react component in the desgn system with a rudimentary interface
2. Create a new story (you can use `Boilerplate.stories.tsx` to get started)
3. Develop the details of the new react component
4. Create stories for all interesting use cases. There should be a story for the most common parameter combinations.
5. Test the new component in your app. If something is off, think about how you can solve it in the system—avoid visual hacking in the app.
</div>

View file

@ -1,11 +0,0 @@
import { Meta } from '@storybook/blocks';
<Meta title="About" />
# Welcome to Admin X Design System
Work in progress!
## Install
Should be something like `yarn add @tryghost/admin-x-ds`

Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB