Skip to content

Commit

Permalink
Update content
Browse files Browse the repository at this point in the history
  • Loading branch information
1aron committed Jun 14, 2024
1 parent 10dc76b commit 627cabd
Show file tree
Hide file tree
Showing 59 changed files with 2,948 additions and 950 deletions.
3,221 changes: 2,565 additions & 656 deletions pnpm-lock.yaml

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion site/app/[locale]/guide/applying-conditionally/metadata.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import define from 'internal/utils/metadata'
const metadata = define({
title: 'Applying Conditionally',
description: 'Apply styles based on theme, print, and other modes and queries.',
category: 'Syntax Tutorial',
category: 'Tutorial',
order: 3,
disabled: true,
filename: import.meta.url
Expand Down
4 changes: 2 additions & 2 deletions site/app/[locale]/guide/content.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ export const categories = getUnitCategories('guide')
{categories.find(category => category.name === 'Getting Started').definedMetadataList}
</OverviewButtons>

## Syntax Tutorial
## Tutorial
<OverviewButtons>
{categories.find(category => category.name === 'Syntax Tutorial').definedMetadataList}
{categories.find(category => category.name === 'Tutorial').definedMetadataList}
</OverviewButtons>

## Fundamentals
Expand Down
217 changes: 10 additions & 207 deletions site/app/[locale]/guide/global-styles/content.mdx
Original file line number Diff line number Diff line change
@@ -1,222 +1,25 @@
## Using official package [sr-only]
## Use official package [sr-only]
The official [Normal CSS](https://github.com/master-co/normal.css) is a **~600B** lightweight CSS package, is similar to [modern-normalize](https://github.com/sindresorhus/modern-normalize) and [normalize.css](https://github.com/necolas/normalize.css) you are familiar with but better:

- [Consistency](#consistency): Keep element styles consistent across browsers.
- [Elimination](#elimination): Remove browser default styles for a better start.
- [Improvement](#improvement): Support responsive media and better text rendering.
- Keep element styles consistent across browsers.
- Remove browser default styles for a better start.
- Support responsive media and better text rendering.
- [and more...](/reference/normal-css#consistency)

`npm install @master/normal.css` and import it in your global CSS file:
Just import it into a global CSS file.
```css
@import '@master/normal.css';
```
<details>
<summary>Paste the CDN or import on-demand through modularization.</summary>
<div>
```html
<link href="https://cdn.master.co/normal.css" rel="stylesheet">
```
Or import on-demand:
<Code lang="css">
{require('!!raw-loader!@master/normal.css/src/index.css').default.replace(/(..\/)\b/g, '@master/normal.css/')}
</Code>
</div>
</details>

---

## Consistency
### Consistent abbreviation styles
Fixed the inconsistent appearance of `html <abbr>` across browsers.
<Code lang="css">
{require('!!raw-loader!@master/normal.css/consistent-abbreviation-styles.css').default}
</Code>

### Consistent control styles
Fixed the inconsistent appearance of controls across browsers.
<Code lang="css">
{require('!!raw-loader!@master/normal.css/consistent-control-styles.css').default}
</Code>

### Consistent horizontal lines
Fixed the inconsistent appearance of horizontal lines across browsers.
<Demo $py={0}>
<DemoPanel className="grid-cols:2 gap:8x gap:12x@sm w:full">
<div>
<small>Before</small>
<hr className="mt:20! mb:0! {all:revert}" />
</div>
<div>
<small>After</small>
<hr className="mt:20! mb:0! border-color:inherit!" />
</div>
</DemoPanel>
</Demo>
<Code lang="css">
{require('!!raw-loader!@master/normal.css/consistent-horizontal-lines.css').default}
</Code>

### Consistent bold styles
Fixed the inconsistent font weight of `html <b>` and `html <strong>` across browsers.
<Code lang="css">
{require('!!raw-loader!@master/normal.css/consistent-bold-styles.css').default}
</Code>

### Consistent code styles
Fixed the inconsistent font size of code-related elements across browsers.
<Code lang="css">
{require('!!raw-loader!@master/normal.css/consistent-code-styles.css').default}
</Code>

### Consistent small styles
Fixed the inconsistent font size of `html <small>` across browsers.
<Code lang="css">
{require('!!raw-loader!@master/normal.css/consistent-small-styles.css').default}
</Code>

### Consistent superscript and subscript styles
Fixed the inconsistent appearance of superscripts and subscripts across browsers.
<Demo $py={0}>
<DemoPanel>
<p className="my:0">This paragraph contains a <sub>subscript</sub> and a <sup>superscript</sup>.</p>
</DemoPanel>
</Demo>
<Code lang="css">
{require('!!raw-loader!@master/normal.css/consistent-superscript-subscript.css').default}
</Code>

### Consistent table styles
Fixed the inconsistent appearance of tables across browsers.
<Code lang="css">
{require('!!raw-loader!@master/normal.css/consistent-table-styles.css').default}
</Code>

### Intuitive sizing control
Control the size of elements more intuitively, including content and padding, without worrying about the impact of padding and borders on dimensions.
<Code lang="css">
{require('!!raw-loader!@master/normal.css/intuitive-sizing-control.css').default}
</Code>

---

## Elimination
### Remove anchor styles
The `html <a>` element usually serves as more than just an inline text link; it could be a button, navigation, or even a card.

Removing its default underline and inheriting the parent color allows you to start with a clean style.
<Demo $py={0}>
<DemoPanel className="grid-cols:2 gap:8x gap:12x@sm">
<div>
<small>Before</small>
<a href="#" className="mt:10 block text:underline fg:revert">Learn more</a>
</div>
<div>
<small>After</small>
<a href="#" className="mt:10 block">Learn more</a>
</div>
</DemoPanel>
</Demo>
<Code lang="css">
{require('!!raw-loader!@master/normal.css/remove-anchor-styles.css').default}
</Code>

### Remove control styles
Inherit the font family, size, and color of control elements from the parent's settings and remove spacing and background as a cleaner starting point.
<Code lang="css">
{require('!!raw-loader!@master/normal.css/remove-control-styles.css').default}
</Code>

### Remove default borders and preset to solid style
Remove borders from all elements to give you the freedom to fully customize the appearance of your elements, preset to the most used solid style.
<Code lang="css">
{require('!!raw-loader!@master/normal.css/remove-default-borders.css').default}
</Code>

### Remove default spacing
Setting margins and padding to zero allows you to customize the appearance and spacing of elements without worrying about the impact of default browser styles.
<Code lang="css">
{require('!!raw-loader!@master/normal.css/remove-default-spacing.css').default}
</Code>

### Remove list styles
Remove the `ul` styles while retaining it as a commonly used structural markup for elements like the navbar and menu.
<Code lang="css">
{require('!!raw-loader!@master/normal.css/remove-list-styles.css').default}
</Code>

### Remove tap highlight color
You should customize the tap highlight color based on current UI features rather than relying on the default.
<Code lang="css">
{require('!!raw-loader!@master/normal.css/remove-tap-highlight.css').default}
</Code>
The `-webkit-tap-highlight-color` CSS property controls the highlight color that appears when an element is tapped on a mobile device, such as Safari and some WebKit-based mobile browsers.

### Eliminate click delays
Disable double-click to zoom on links, input fields, and buttons to improve responsiveness for touch devices.
<figure>
<iframe className="aspect:16/9 w:full" src="https://www.youtube.com/embed/AjUpiwvIa5A?si=qatiz-LszvYqE15c&amp;controls=0" title="YouTube video player" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen></iframe>
<figcaption>[300ms tap delay, gone away](https://developer.chrome.com/blog/300ms-tap-delay-gone-away)</figcaption>
</figure>
<Code lang="css">
{require('!!raw-loader!@master/normal.css/eliminate-click-delays.css').default}
</Code>
An instantly responsive UI enables users to confidently press each button without pausing and waiting for a response. To learn more about the influence of human reaction times and web performance, explore the [introduction to RAIL](https://web.dev/articles/rail).

(x) Disabling `user-scalable=no` can harm user experience, accessibility, and mobile-friendliness and have negative SEO implications.
```html
<meta name="viewport" content="width=device-width, **user-scalable=no**">
```

---

## Improvement
### Better text rendering and appearance
Ensure consistent, clear, high-quality text and font appearance across various browsers.
<Code lang="css">
{require('!!raw-loader!@master/normal.css/better-text-appearance.css').default}
</Code>

### Readable tab size
Setting the tab size to 4 makes the code more structured and easier to read.
<Code lang="css">
{require('!!raw-loader!@master/normal.css/readable-tab-size.css').default}
</Code>

### Responsive friendly media elements
Preset the maximum width of media-related elements to the parent container to make them responsive.
<Demo>
<div className="grid-cols:2 gap:20">
<div>
<small>Before</small>
<div className="mt:10 b:1|crimson-40 square overflow:hidden">
<Image src={require('~/site/public/images/chicken.png').default} width={500} height={500} alt="No responsive image" className="max-w:none" />
</div>
</div>
<div>
<small>After</small>
<div className="mt:10 b:1|green-40 square">
<Image src={require('~/site/public/images/chicken.png').default} width={500} height={500} alt="Responsive image" />
</div>
</div>
</div>
</Demo>
<Code lang="css">
{require('!!raw-loader!@master/normal.css/responsive-media-elements.css').default}
</Code>
Browsers default these elements to `inline` display. `block` can be centered using common tricks like `margin: auto`.

For media that needs to overflow the container, you can cancel the maximum width by selecting descendants:
```html
<article class="**max-w:none_:where(img)**">…</article>
```

---

## Using syntax
### Stylizing descendant elements
## Style descendant elements
Customize your fonts, foreground color, etc., add syntax in `html <body class="…">` and rely on native inheritance behavior or use CSS selectors to preset global styles.

(o) Use zero [specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) `css :where()` to select elements and preset styles.
```html
<body class="font:sans **font:mono_:where(code,pre)**">…</body>
```
Otherwise, you risk falling into `css !important` hell with `css :is()` and `css _` descendant selectors.
Otherwise, you risk falling into `css !important` hell with `css :is()` and `css _` descendant selectors.

You can also add `@preset` to lower it to the preset layer to make it even lower in priority.
4 changes: 2 additions & 2 deletions site/app/[locale]/guide/global-styles/metadata.ts
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
import define from 'internal/utils/metadata'

const metadata = define({
title: 'Global Styles',
title: 'Presetting global styles',
description: 'Normalize browser and preset global styles for more concise-style programming.',
category: 'First Build',
category: 'Start Building',
other: {
subject: 'Global Styles'
},
Expand Down
2 changes: 1 addition & 1 deletion site/app/[locale]/guide/global-styles/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ export async function generateMetadata(props: any, parent: any) {

export default async function Page(props: any) {
return (
<Layout {...props} pageCategories={getUnitCategories('guide')} pageDirname={__dirname} metadata={metadata} toc={toc} h2Big>
<Layout {...props} $type="prose" pageCategories={getUnitCategories('guide')} pageDirname={__dirname} metadata={metadata} toc={toc} h2Big>
<Content />
</Layout >
)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ export default () => <CodeTabs>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="preload" as="script" href="https://cdn.master.co/css-runtime@rc">
<link rel="preload" as="style" href="https://cdn.master.co/normal.css@rc">
<link rel="stylesheet" href="https://cdn.master.co/normal.css@rc">
<link rel="preload" as="style" href="https://cdn.master.co/normal.css">
<link rel="stylesheet" href="https://cdn.master.co/normal.css">
<script>
window.masterCSSConfig = {
variables: {
Expand All @@ -38,8 +38,8 @@ export default () => <CodeTabs>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://cdn.master.co/normal.css@rc">
<link rel="preload" as="style" href="https://cdn.master.co/normal.css@rc">
<link rel="stylesheet" href="https://cdn.master.co/normal.css">
<link rel="preload" as="style" href="https://cdn.master.co/normal.css">
<link rel="modulepreload" href="https://cdn.master.co/css-runtime@rc/+esm">
+ <script type="module">
+ import { initCSSRuntime } from 'https://cdn.master.co/css-runtime@rc/+esm'
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Copy and paste [CDNs](/guide/installation#cdn-providers) to instantly launch the
### <StepNum />Start in one step
Copy and paste to start styling your first element with Master CSS!
<CDNCodes />
<p className="mt:12x">Open your browser to watch the changes.</p>
Open your browser to watch the changes.
<HelloWorld />
</Step>
</StepSection>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ The easiest way to use Master CSS from scratch is to initialize the [runtime eng
</body>
</html>
```
<p className="mt:12x">Open your browser to watch the changes.</p>
Open your browser to watch the changes.
<HelloWorld />
</Step>
</StepSection>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import define from 'internal/utils/metadata'

const metadata = define({
title: 'General Installation',
description: 'The easiest way to use Master CSS from scratch is to initialize the runtime engine directly in the application\'s entry file.',
description: 'The easiest way to use Master CSS from scratch is to initialize the runtime engine directly in the entry file.',
category: 'Getting Started',
filename: import.meta.url
})
Expand Down
2 changes: 1 addition & 1 deletion site/app/[locale]/guide/installation/(tabs)/metadata.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ const metadata = define({
title: {
absolute: 'Installing Master CSS'
},
description: 'Master CSS allows you to install from package managers, copy and paste from CDNs, and even integrate with frameworks.',
description: 'Master CSS allows you to install from package managers, copy-paste CDNs, and even integrate with frameworks.',
category: 'Getting Started',
other: {
subject: 'Installation'
Expand Down
2 changes: 1 addition & 1 deletion site/app/[locale]/guide/installation/angular/content.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ import ProgressiveRenderingIntro from '../../rendering-modes/components/Progress
```html name=src/app/app.component.html
<h1 class="**font:40** **font:heavy** **italic** **m:12x** **text:center**">Hello World</h1>
```
<p className="mt:12x">Open your browser to watch the changes.</p>
Open your browser to watch the changes.
<HelloWorld url="localhost:3000" />
</Step>
</StepSection>
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ import RuntimeRenderingIntro from '../../../rendering-modes/components/RuntimeRe
```html name=src/app/app.component.html
<h1 class="**font:40** **font:heavy** **italic** **m:12x** **text:center**">Hello World</h1>
```
<p className="mt:12x">Open your browser to watch the changes.</p>
Open your browser to watch the changes.
<HelloWorld url="localhost:3000" />
</Step>
</StepSection>
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ import StaticExtractionIntro from '../../../rendering-modes/components/StaticExt
```html name=src/app/app.component.html
<h1 class="**font:40** **font:heavy** **italic** **m:12x** **text:center**">Hello World</h1>
```
<p className="mt:12x">Open your browser to watch the changes.</p>
Open your browser to watch the changes.
<HelloWorld url="localhost:3000" />
</Step>
</StepSection>
2 changes: 1 addition & 1 deletion site/app/[locale]/guide/installation/astro/content.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ import RuntimeRenderingIntro from '../../rendering-modes/components/RuntimeRende
</main>
</Layout>
```
<p className="mt:12x">Open your browser to watch the changes.</p>
Open your browser to watch the changes.
<HelloWorld url="localhost:3000" />
</Step>
</StepSection>
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,7 @@ import StaticExtractionIntro from '../../../rendering-modes/components/StaticExt
</main>
</Layout>
```
<p className="mt:12x">Open your browser to watch the changes.</p>
Open your browser to watch the changes.
<HelloWorld url="localhost:3000" />
</Step>
</StepSection>
2 changes: 1 addition & 1 deletion site/app/[locale]/guide/installation/blazor/content.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ import RuntimeRenderingIntro from '../../rendering-modes/components/RuntimeRende
}
]}
</CodeTabs>
<p className="mt:12x">Open your browser to watch the changes.</p>
Open your browser to watch the changes.
<HelloWorld url="localhost:3000" />
</Step>
</StepSection>
Loading

0 comments on commit 627cabd

Please sign in to comment.