Skip to content

Commit

Permalink
chore(Docs): formats mdx documents (#2044)
Browse files Browse the repository at this point in the history
  • Loading branch information
langz authored and tujoworker committed May 31, 2023
1 parent 954ea0e commit db679f4
Show file tree
Hide file tree
Showing 130 changed files with 1,022 additions and 730 deletions.
6 changes: 5 additions & 1 deletion packages/dnb-design-system-portal/src/docs/contribute.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,11 @@ description: 'Project overview, development guides, conventions etc.'

import { Button } from '@dnb/eufemia/src'
import Card from 'dnb-design-system-portal/src/shared/menu/Card'
import { NewContributor, GettingStarted, Principles } from 'Docs/contribute/assets/graphics'
import {
NewContributor,
GettingStarted,
Principles,
} from 'Docs/contribute/assets/graphics'

# Contributing to Eufemia

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,9 @@ import { Button } from '@dnb/eufemia/src'

For all discussion topics, ask in Slack:

<Button href="https://dnb-it.slack.com/archives/CMXABCHEY">#eufemia-web</Button>
<Button href="https://dnb-it.slack.com/archives/CMXABCHEY">
#eufemia-web
</Button>

### Related channels in [DNB IT](https://dnb-it.slack.com)

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,13 @@ import { Button, Blockquote, Section } from '@dnb/eufemia/src'
If you are new to the Eufemia Library, we would recommend following an intro to the elementary parts of Eufemia.

<Section style_type="mint-green" spacing>
<Button href="/uilib/intro" size="large" text="Quick Intro" icon="chevron_right" variant="secondary"/>
<Button
href="/uilib/intro"
size="large"
text="Quick Intro"
icon="chevron_right"
variant="secondary"
/>
</Section>

## Your first contribution
Expand Down Expand Up @@ -44,7 +50,13 @@ More information in [Style guides - Git convention](/contribute/style-guides/git
Have a look at the "before getting started" section for a description of technical details. In this section, you will find what packages are included, design decisions explained, the format of the component structure, what purpose different files have, what happens during a build, and the different development environments.

<Section style_type="mint-green" spacing>
<Button href="/contribute/first-contribution/before-started" size="large" text="Before getting started" icon="chevron_right" variant="secondary" />
<Button
href="/contribute/first-contribution/before-started"
size="large"
text="Before getting started"
icon="chevron_right"
variant="secondary"
/>
</Section>

## What to expect from the maintainers
Expand All @@ -56,8 +68,18 @@ As of this date, there are only a few maintainers. That means you can expect **l
## Next step

<Blockquote className="dnb-blockquote--no-background">
The best way to understand a project is to just jump on a real task. It is scary, but the easiest and quickest way of getting into a new project. Also, you should not be afraid of having an imperfect commit, that's really what pull requests are for!
<cite>Dina, new contributor</cite>
The best way to understand a project is to just jump on a real task. It
is scary, but the easiest and quickest way of getting into a new project.
Also, you should not be afraid of having an imperfect commit, that's
really what pull requests are for!
<cite>Dina, new contributor</cite>
</Blockquote>

<Button href="/contribute/getting-started" size="large" text="Next up: Getting started" icon="chevron_right" variant="tertiary" bottom="2rem"/>
<Button
href="/contribute/getting-started"
size="large"
text="Next up: Getting started"
icon="chevron_right"
variant="tertiary"
bottom="2rem"
/>
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,13 @@ Every component and extension should have a similar structure, as described here

As an example, we show the folder structure of component Breadcrumb. You can also check out the [source on Github](https://github.com/dnbexperience/eufemia/tree/main/packages/dnb-eufemia/src/components/breadcrumb).

<InlineImg src="/images/folder-structure.png" width="360" caption="Folder structure of component Breadcrumb" alt="Folder structure with tests, style, typescript files and index files" right/>
<InlineImg
src="/images/folder-structure.png"
width="360"
caption="Folder structure of component Breadcrumb"
alt="Folder structure with tests, style, typescript files and index files"
right
/>

1. **`/__tests__`**: Contains the tests (`Breadcrumb.test.tsx`) and screenshot tests (`Breadcrumb.screenshot.test.tsx`) for the component. All screenshots will be placed within the folder `__snapshots__`.
1. **`/style`**: Contains the styling of the component. The file `_breadcrumb.scss` defines all styling using [BEM](http://getbem.com/naming/). `dnb-breadcrumb.scss` contains the component style exports.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ import { Hr } from '@dnb/eufemia/src'
You are now ready to get started. Here you will find a step-by-step guide to making changes in the Eufemia repo.
If you are new to the repository, first check out [what I should know before getting started](/contribute/first-contribution#what-should-i-know-before-getting-started).

<Toc />
<Toc />

<Hr top="large" light />

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,4 +16,8 @@ git clone https://github.com/dnbexperience/eufemia.git

- or **Fork** the repo by clicking `Fork` in the top right corner in [Eufemia on GitHub](https://github.com/dnbexperience/eufemia).

<InlineImg src="/images/fork-repo.png" width="500" alt="Fork button location on Github" />
<InlineImg
src="/images/fork-repo.png"
width="500"
alt="Fork button location on Github"
/>
Original file line number Diff line number Diff line change
Expand Up @@ -72,5 +72,11 @@ Anyone asked to stop unacceptable behavior is expected to comply immediately. If
You may use [this "reproduction" starter](!/issue) to reproduce the issue when reporting.

<Section style_type="mint-green" spacing>
<Button href="/issue" size="large" text="Starter" target="_blank_" variant="secondary"/>
<Button
href="/issue"
size="large"
text="Starter"
target="_blank_"
variant="secondary"
/>
</Section>
Original file line number Diff line number Diff line change
Expand Up @@ -83,10 +83,22 @@ git fetch origin && git rebase origin/main

When you have committed changes to your branch, go to [Github Pull Requests](https://github.com/dnbexperience/eufemia/pulls) and open a `New pull request`.

<InlineImg src="/images/pull-request.png" width="900" alt="Screenshot of the location of new pull request button on Github" top bottom/>
<InlineImg
src="/images/pull-request.png"
width="900"
alt="Screenshot of the location of new pull request button on Github"
top
bottom
/>

You will most likely get the yellow notification bar mentioning that a branch had a recent push. Click on the `Compare and pull request` button. This will take you to the page for opening a pull request. Fill out the template under the `Write tab`.

<InlineImg src="/images/pull-request-part-2.png" width="900" alt="Screenshot of opening a new pull request on Github" top bottom/>
<InlineImg
src="/images/pull-request-part-2.png"
width="900"
alt="Screenshot of opening a new pull request on Github"
top
bottom
/>

Request a reviewer, create the pull request and watch the results of the pipeline checks.
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,22 @@ When reporting issues on GitHub, you need to have a [GitHub account](https://git

First step is to click on the `New issue` button in the `Issues tab` on GitHub.

<InlineImg src="/images/report-issue.png" width="900" alt="Screenshot of the location of new issue button on GitHub" top bottom/>
<InlineImg
src="/images/report-issue.png"
width="900"
alt="Screenshot of the location of new issue button on GitHub"
top
bottom
/>

The next step will show you all the possibilities for new issues. Create a new `Bug Report` or a `Feature Proposal` to go next.

<InlineImg src="/images/report-issue-part-2.png" width="900" alt="Screenshot of the possibilities in creating a new issue" top/>
<InlineImg
src="/images/report-issue-part-2.png"
width="900"
alt="Screenshot of the possibilities in creating a new issue"
top
/>

These will each have a prepared template you need to fill out in order to submit your issue.

Expand Down
2 changes: 1 addition & 1 deletion packages/dnb-design-system-portal/src/docs/icons.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: 'List of all Eufemia icons.'
order: 1
---

import ListAllIcons from "dnb-design-system-portal/src/shared/parts/icons/ListAllIcons";
import ListAllIcons from 'dnb-design-system-portal/src/shared/parts/icons/ListAllIcons'

# Icons

Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,9 @@
import { InfoIcon, WarnIcon, ErrorIcon, MarketingIcon} from '@dnb/eufemia/src/components/form-status/FormStatus'
import {
InfoIcon,
WarnIcon,
ErrorIcon,
MarketingIcon,
} from '@dnb/eufemia/src/components/form-status/FormStatus'

## Use the [**FormStatus**](/uilib/components/form-status) icons only

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ icon: 'primary'
order: 2
---

import ListAllIcons from "dnb-design-system-portal/src/shared/parts/icons/ListAllIcons";
import ListAllIcons from 'dnb-design-system-portal/src/shared/parts/icons/ListAllIcons'

# Primary Icons

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ icon: 'secondary'
order: 3
---

import ListAllIcons from "dnb-design-system-portal/src/shared/parts/icons/ListAllIcons";
import ListAllIcons from 'dnb-design-system-portal/src/shared/parts/icons/ListAllIcons'

# Secondary Icons

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,18 @@ Be aware that the default text styling in Eufemia does not include top and botto

The first image below shows how the final form looks. The second image highlights some of the vertical and horizontal spacing in the design.

<InlineImg src={InspirationSkadeforsikringNoGuides} caption="Form example with alternating sections" alt="Example of a form" />
<InlineImg
src={InspirationSkadeforsikringNoGuides}
caption="Form example with alternating sections"
alt="Example of a form"
/>

## Using Eufemia's spatial system for layout

Even though there is a lot of freedom built into the Eufemia system regarding how UI layout designs should be, it is recommended to use the standard spacers found in the Eufemia library to attain a visually consistent look. The example above is laid out with the standard spacers and these are highlighted in the duplicate example below:

<InlineImg src={InspirationSkadeforsikring} caption="Form example with vertical spacing and some horizontal highlighted" alt="Example of a form with spacing highlighted" />
<InlineImg
src={InspirationSkadeforsikring}
caption="Form example with vertical spacing and some horizontal highlighted"
alt="Example of a form with spacing highlighted"
/>
Original file line number Diff line number Diff line change
Expand Up @@ -16,37 +16,39 @@ import TablesSpace from 'Docs/quickguide-designer/assets/tables-space.svg'

Eufemia makes use of a very simple 8px unit grid. Margins, paddings, and distances consist of multiples of 8 (mostly - sometimes half and quarter units are required). If we were to combine multiples of this 8px 'space block', we could end up with something like this:

<InlineImg src={NamingSpace} caption="Naming space units" alt="Naming space units" />
<InlineImg
src={NamingSpace}
caption="Naming space units"
alt="Naming space units"
/>

These titles can then be transferred to components, for example, tables. A 'medium' table would refer to the amount of padding in the cells.

<InlineImg src={TablesSpace} caption="Applying space to tables" alt="Applying space to tables" />
<InlineImg
src={TablesSpace}
caption="Applying space to tables"
alt="Applying space to tables"
/>

The same can apply to components such as cards, form rows, etc. Responsive breakpoints can switch between these spacing units to expand or contract the overall size of an object.

## Naming Colors

Eufemia for the web uses a simple naming system:

<div class="typography-box">
Color name + percentage
</div>
<div class="typography-box">Color name + percentage</div>

Depending on where the color will be used, its name formation will be different. For example, in Figma (and other design tools), the name is constructed thus:

The color name is written with spaces between words. The first word starts with capital. Some color names have a percentage sign denoting the tint value.

Example:

<div class="typography-box">
Fire red 8%
</div>
<div class="typography-box">Fire red 8%</div>

Whereas in CSS as a custom property this is written:

<div class="typography-box">
--color-fire-red-8
</div>
<div class="typography-box">--color-fire-red-8</div>

Colors have a naming convention across all platforms and formats. Please refer to the table in [colors section](/quickguide-designer/colors).

Expand All @@ -60,22 +62,16 @@ However, to maintain consistency, in Figma we name Pages and Frames (canvases) w

Example of a Figma Page name:

<div class="typography-box">
04 Spacing & Common components
</div>
<div class="typography-box">04 Spacing & Common components</div>

Example of a Figma Frame name:

<div class="typography-box">
02 Spacing components - horizontal
</div>
<div class="typography-box">02 Spacing components - horizontal</div>

Actual components are written with all small letters.

Example of a Figma component name:

<div class="typography-box">
date picker
</div>
<div class="typography-box">date picker</div>

If in doubt, look at the main Eufemia file - [Eufemia - Web](https://www.figma.com/file/cdtwQD8IJ7pTeE45U148r1/Eufemia-Web?node-id=530%3A49).
Loading

0 comments on commit db679f4

Please sign in to comment.