Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(design): update getting started docs #3271

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from
Open

docs(design): update getting started docs #3271

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
27a2650
docs(design): update getting started docs
xelaint Oct 16, 2024
393d1e4
update docs
xelaint Oct 16, 2024
ed1f444
address comments
xelaint Oct 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 44 additions & 66 deletions libs/design/guides/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,96 +1,74 @@
# Introduction
Get started with `@daffodil/design`, an Angular component library built for ecommerce with accessibility in-mind. With these first steps, we warmly welcome you to a library that will help you build elegant and accessible user interfaces without having to do everything by hand.
# Getting started
This guide is designed to touch upon the very basics of `@daffodil/design` to get you up and running quickly. It includes information on prerequisites, installation steps, and how to use a component.

## First Steps
This tutorial is designed to touch upon the very basics of the `@daffodil/design` library. First things first, you will need to [create a new Angular project](https://angular.io/cli) and [install the library](#installation). By the end of this tutorial, you will have created a basic Angular app that renders a simple `DaffHeroComponent` with a title and subtitle.
## Before you begin
`@daffodil/design` is designed to be used with Angular. Make sure [Angular CLI](https://angular.io/cli) has been installed before you begin. You'll also need a pakcage manager like [npm](https://www.npmjs.com/package/@daffodil/design) or [Yarn](https://yarnpkg.com/package?q=%40daffodil%2Fdesign&name=%40daffodil%2Fdesign).

`@daffodil/design` is built with [Sass](https://sass-lang.com/), so we recommend you learn it!

## Installation
`@daffodil/design` is designed to be used with Angular. If you have not already done so, [create a new Angular project](https://angular.io/cli). Afterwards, `@daffodil/design` can be installed using a [package manager](https://www.npmjs.com/package/@daffodil/design).
To install `@daffodil/design`, use the following commands in your terminal:

### npm
Install with npm:
```bash
npm install --save @daffodil/design @daffodil/core \
@angular/animatio@^13.0.0 \
@angular/cdk@^13.0.0 \
@fortawesome/angular-fontawesome@^0.10.0 \
@fortawesome/fontawesome-svg-core@^1.0.0 \
@fortawesome/free-solid-svg-icons@^5.2.0 \
@fortawesome/free-brands-svg-icons@^5.2.0 \
@fortawesome/free-regular-svg-icons@^5.2.0 \
modern-normalize@^0.5.0
npm install @daffodil/design --save
```

> If you are using Node.js v14 or higher, you can simply run: `npm install --save @daffodil/design`

### Yarn
Install with Yarn:
```bash
yarn add @daffodil/design @daffodil/core \
@angular/animatio@^13.0.0 \
@angular/cdk@^13.0.0 \
@fortawesome/angular-fontawesome@^0.10.0 \
@fortawesome/fontawesome-svg-core@^1.0.0 \
@fortawesome/free-solid-svg-icons@^5.2.0 \
@fortawesome/free-brands-svg-icons@^5.2.0 \
@fortawesome/free-regular-svg-icons@^5.2.0 \
modern-normalize@^0.5.0
yarn add @daffodil/design
```

> If you are using Node.js v14 or higher, you can simply run: `yarn add @daffodil/design`

### Modify Angular.json
Next, create a `styles.scss` in the root of the Angular app and modify the `angular.json`'s `projects.[my-app].architect.build.options.styles` to look as below. If SASS is already in use in the application and the stylesheet already exists, this step can be skipped.
## Set up your style environment
1. Create a `styles.scss` in the root of your Angular app.
2. Add the stylesheet to your `angular.json` file. This step can be skipped if SASS is already in use in the application and the stylesheet already exists.

```json
"styles": [
"src/styles.scss"
],
"projects": {
"app-name": {
"architect": {
"build": {
"options": {
"styles": [
"src/styles.scss"
],
}
}
}
}
}
```

> Note that `@daffodil/design` uses SASS, [so we recommend you learn it!](https://sass-lang.com/)

### Add the Global Styles
There is a minimal required global style for `@daffodil/design` to operate effectively in all supported browsers. Update the `styles.scss` to include the following:
### Add global styles
There is a minimal required global style for the Daffodil Design System to operate effectively in all supported browsers. Update your `styles.scss` file to include the following:

```scss
@forward '@daffodil/design/scss/global';
```

> For more information on our approach to these kinds of styles, see the ["Global Styles" guide.](/libs/design/guides/global-styles.md)
> For more information on our approach to these kinds of styles, see the [Global Styles guide.](/libs/design/guides/foundations/global-styles.md)

### Add a Theme
`@daffodil/design` is a themable component library. The components in the design library can be configured with customized colors in addition to a dark AND light mode for those same colors.
## Add a theme
`@daffodil/design` is a themable component library. The components in the design library can be configured with customized colors in addition to a dark and light mode for those same colors. No further configuration is needed if you choose to use `@daffodil/design`'s default theme.

damienwebdev marked this conversation as resolved.
Show resolved Hide resolved
> Are you excited by themes? So are we.
See the [Theming guide](/libs/design/scss/theming/README.md) if you'd like to define your own theme.

See the [Theming Docs](/libs/design/scss/theming/README.md)

### Use a Component
In the `AppModule` of your Angular app, import the `DaffHeroModule` into the `NgModule`'s `imports` array.
## Use a component
Now you're ready to use Daffodil Design [components](/docs/design/components)! For example, here's how to use the [Hero](/libs/design/hero/README.md) component.

```ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { AppComponent } from './app.component';
import { DaffHeroModule } from '@daffodil/design/hero';

@NgModule({
@Component({
standalone: true,
selector: 'custom-component',
templateUrl: './custom-component.component.html',
imports: [
BrowserModule,
DaffHeroModule
],
declarations: [
AppComponent
DAFF_HERO_COMPONENTS,
],
bootstrap: [
AppComponent
]
})
export class AppModule {}
export class CustomComponent {}
```

### Update the Template
With the module imported, the `AppComponent` template can be updated to render the component.
With the component imported, you can add it to your `CustomComponent` template like so:

```html
<daff-hero>
Expand All @@ -103,5 +81,5 @@ With the module imported, the `AppComponent` template can be updated to render t
</daff-hero>
```

## Next Steps
We've just walked through the basics of setting up the `@daffodil/design` library. There is much more to it than just the `DaffHeroComponent`. Check out the full list of available components, try and add them to your sample app, and imagine all the wonderful things you can now build!
## Next steps
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe leave a small challenge here? Something like "try to change the color of the hero" and link to the docs of the hero component?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added

We've just walked through the basics of setting up `@daffodil/design`. There is much more to it than just the hero component. Check out the [full list of components](/docs/design/components), try and add them to your sample app, and imagine all the wonderful things you can now build!
Loading