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:
parent
a6e534bba8
commit
e4cac91e19
4 changed files with 114 additions and 11 deletions
41
ghost/admin-x-settings/src/admin-x-ds/docs/About.mdx
Normal file
41
ghost/admin-x-settings/src/admin-x-ds/docs/About.mdx
Normal 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>
|
73
ghost/admin-x-settings/src/admin-x-ds/docs/Develop.mdx
Normal file
73
ghost/admin-x-settings/src/admin-x-ds/docs/Develop.mdx
Normal 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>
|
|
@ -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 |
Loading…
Add table
Reference in a new issue