Skip to content

Commit d283883

Browse files
bradwalkbradwalk
committed
work in progress - updating Front-end dev docs to reflect change to Astro
1 parent db1b2b5 commit d283883

7 files changed

Lines changed: 99 additions & 80 deletions

File tree

‎docs/accelerator/06-icl.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: idfive Component Library (ICL) - Wireframe and component library fo
66

77
The idfive Component Library (ICL) is a comprehensive wireframe and component library that serves as the foundation for Accelerator projects. It provides standardized design patterns, components, and layouts that ensure consistency across all idfive projects.
88

9-
For complete technical documentation on ICL implementation, build process, and development workflow, see the **[ICL Technical Documentation](/docs/front-end/pattern-lab)**.
9+
For complete technical documentation on ICL implementation, build process, and development workflow, see the **[ICL Technical Documentation](/docs/front-end/idfive-component-library)**.
1010

1111
## Design Resources
1212

@@ -20,7 +20,7 @@ The ICL directly influences Accelerator project structure and provides the found
2020

2121
- **Header Configuration**: Site Options reference ICL Header Types (Full vs Hybrid)
2222
- **Component Sync**: ICL components are manually synced to both [Drupal Accelerator](https://dev-idfive-drupal-accelerator.pantheonsite.io/) and [WordPress Accelerator](https://dev-idfive-accelerator.pantheonsite.io/) sites
23-
- **Pattern Library**: All Accelerator components follow ICL design patterns established in the [Pattern Lab environment](/docs/front-end/pattern-lab)
23+
- **Pattern Library**: All Accelerator components follow ICL design patterns established in the [Pattern Lab environment](/docs/front-end/idfive-component-library)
2424
- **Wireframe Foundation**: Project wireframes are built using ICL components
2525
- **Consistency Standards**: Ensures all projects maintain idfive design standards
2626

@@ -29,7 +29,7 @@ The ICL directly influences Accelerator project structure and provides the found
2929
### Header Types
3030

3131
- **Full Header**: Complete navigation with all elements visible
32-
- **Hybrid Header**: Streamlined navigation with selective element display
32+
- **Hybrid Header**: Streamlined navigation with selective element display
3333
- **Mobile Navigation**: Responsive navigation patterns for mobile devices
3434

3535
### Content Components
@@ -55,7 +55,7 @@ The ICL is built using modern frontend tools and is available as a Pattern Lab e
5555
- **Component Library**: TypeScript modules with accessibility utilities
5656
- **Staging Environment**: Available at [staging site](https://staging2.idfive.com/idfive-pattern-lab-starter/public/?p=pages-welcome) (username/password: `guest`)
5757

58-
For complete setup instructions, build process, and component documentation, see **[ICL Technical Documentation](/docs/front-end/pattern-lab)**.
58+
For complete setup instructions, build process, and component documentation, see **[ICL Technical Documentation](/docs/front-end/idfive-component-library)**.
5959

6060
## Usage Guidelines
6161

@@ -68,7 +68,7 @@ When working with Accelerator projects:
6868

6969
## Related Resources
7070

71-
- **[ICL Technical Documentation](/docs/front-end/pattern-lab)** - Complete setup, build process, and component development guide
72-
- [Accelerator Overview](/docs/accelerator/overview) - Project overview and design resources
71+
- **[ICL Technical Documentation](/docs/front-end/idfive-component-library)** - Complete setup, build process, and component development guide
72+
- [Accelerator Overview](/docs/accelerator/overview) - Project overview and design resources
7373
- [Site Options](/docs/accelerator/site-options) - Configuration options that reference ICL header types
7474
- [Customization Guidelines](/docs/accelerator/customization) - How to customize while maintaining ICL consistency

docs/front-end/01-pattern-lab.mdx renamed to docs/front-end/01-idfive-component-library.mdx

Lines changed: 35 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,15 @@ import TabItem from "@theme/TabItem";
1212
## Overview (What's Included)
1313

1414
<Tabs groupId="icl-versions">
15-
<TabItem value="v2.0" label="ICL Version 2+ (Vite/PostCSS)" default>
15+
<TabItem value="v3.0" label="ICL Version 3+ (Astro)" default>
16+
- [Astro](https://astro.build/) static site generator framework
17+
- Includes (out of the box):
18+
- [Vite](https://vite.dev/)
19+
- [PostCSS](https://postcss.org/)
20+
- [Typescript](https://www.typescriptlang.org/)
21+
</TabItem>
22+
23+
<TabItem value="v2.0" label="ICL Version 2+ (Vite/PostCSS)">
1624
- [Pattern Lab](https://patternlab.io/) to display components and pages, specifically the [Node Version](https://github.com/pattern-lab/) with twig
1725
- [Vite](https://vite.dev/) build tool, also includes:
1826
- [PostCSS](https://postcss.org/)
@@ -61,7 +69,11 @@ patternlab-node). The site navigation is typically on the left side of the page
6169
## Build
6270

6371
<Tabs groupId="icl-versions">
64-
<TabItem value="v2.0" label="ICL Version 2+ (Vite/PostCSS)" default>
72+
<TabItem value="v3.0" label="ICL Version 3+ (Astro)" default>
73+
- Run `npm run build`
74+
- To preview the build (`/dist` directory) run `npm run preview`
75+
</TabItem>
76+
<TabItem value="v2.0" label="ICL Version 2+ (Vite/PostCSS)">
6577
**No build step is needed** - the js and css are being built and optimized continuously.
6678
- Run `npm run develop`
6779
</TabItem>
@@ -77,14 +89,30 @@ patternlab-node). The site navigation is typically on the left side of the page
7789

7890
## Folder Structure
7991

80-
The source directory contains the main working areas for the library. More information can be found [here](https://patternlab.io/docs/editing-pattern-lab-source-files/).
81-
8292
<Tabs groupId="icl-versions">
83-
<TabItem value="v2.0" label="ICL Version 2+ (Vite/PostCSS)" default>
93+
<TabItem value="v3.0" label="ICL Version 3+ (Astro)" default>
94+
- **dist** is the build folder, the static assets and pages are re-created here when `npm run build` is run
95+
- **public** static folder where images and favicons (any assets needed) can be placed and accessed as needed
96+
- **src**:
97+
- **assets**:
98+
- **CSS** contains css partial files, compiled into `index.css` (see [css documentation](/docs/front-end/css) for more information)
99+
- **JS** contains all typescript modules:
100+
- **components** contains individual modules for respective components (when required for functionality)
101+
- **utilities** contains helpful accessibility functions that can be used to simply certain tasks
102+
- **main.ts** imports all functions and calls init functions for each (this file gets compiled into one on build)
103+
- **components** contains the `.astro` source files for components
104+
- **data**:
105+
- **global.json** data for use throughout site that will not change, for example the site header and site footer data
106+
- ***.json** data used for all pages of the site, as well as variations on pages (see kitchen sink or home for example)
107+
- **icl-utils** contains utility scripts for ICL usage, not to intended to be edited unless absolutely needed
108+
- **layouts/Layout.astro** the main page structure layout that is used on every page of the site
109+
- **pages** contains the `.astro` source files for pages. The files in the `/components` subdirectory are solely for display in the ICL Pages/Component list view only and not intended to be edited
110+
</TabItem>
111+
<TabItem value="v2.0" label="ICL Version 2+ (Vite/PostCSS)">
84112
- **Annotations** is not in use, but can be used as an alternate way of documenting components (insead of placing the documentation in the respective component folder)
85113
- **Data** contains global data, currently the starter library consists of `data.json` which holds data for global components such as the site-header and site-footer (this prevents the data from needing to be repeated for multiple instances). This can be re-organized/customized to suit developer needs
86114
- **Meta** contains the header and footer code that gets applied to all patterns and pages. `_head.twig` contains all of the html and header starting code and `_foot.twig` for footer and ending html code/tags - more info can be found [here](https://patternlab.io/docs/modifying-the-pattern-header-and-footer/)
87-
- **Patterns** contains the bulk of the code in use (components, core & pages). The three directories in here correlate to what is seen in the browser interface and are documented [above](pattern-lab#interface)
115+
- **Patterns** contains the bulk of the code in use (components, core & pages). The three directories in here correlate to what is seen in the browser interface and are documented [above](idfive-component-library#interface)
88116
- **CSS** contains css partial files, compiled into `index.css` (see [css documentation](/docs/front-end/css) for more information)
89117
- **Fonts** is empty by default (Google Fonts are linked to in `_head.twig` for the sarter version), but local fonts can be added to this directory
90118
- **Images** contains all starter images, as well as icons and svgs
@@ -98,7 +126,7 @@ The source directory contains the main working areas for the library. More infor
98126
- **Annotations** is not in use, but can be used as an alternate way of documenting components (insead of placing the documentation in the respective component folder)
99127
- **Data** contains global data, currently the starter library consists of `data.json` which holds data for global components such as the site-header and site-footer (this prevents the data from needing to be repeated for multiple instances). This can be re-organized/customized to suit developer needs
100128
- **Meta** contains the header and footer code that gets applied to all patterns and pages. `_head.twig` contains all of the html and header starting code and `_foot.twig` for footer and ending html code/tags - more info can be found [here](https://patternlab.io/docs/modifying-the-pattern-header-and-footer/)
101-
- **Patterns** contains the bulk of the code in use (components, core & pages). The three directories in here correlate to what is seen in the browser interface and are documented [above](pattern-lab#interface)
129+
- **Patterns** contains the bulk of the code in use (components, core & pages). The three directories in here correlate to what is seen in the browser interface and are documented [above](idfive-component-library#interface)
102130
- **CSS** contains the scss partial files, compiled into `index.scss` (see [css documentation](/docs/front-end/css) for more information)
103131
- **Fonts** is empty by default (Google Fonts are linked to in `_head.twig` for the sarter version), but local fonts can be added to this directory
104132
- **Images** contains all starter images, as well as icons and svgs

‎docs/front-end/03-page-layout.md‎

Lines changed: 51 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,60 @@
11
# Layout & Page Structure
22

33
## Page Structure
4-
The overall page structure in the [ICL / Pattern Lab Starter](/docs/front-end/pattern-lab) is controlled by `source/_patterns/pages/page-structure.twig`:
4+
5+
The overall page structure in the [ICL / Pattern Lab Starter](/docs/front-end/idfive-component-library) is controlled by `source/_patterns/pages/page-structure.twig`:
56

67
```html
78
<div class="off-canvas">
89
<div class="max-bound">
9-
{% include "@components/emergency-alert/emergency-alert.twig" %}
10-
{% include "@components/site-header/site-header.twig" %}
11-
<main id="main-content">
12-
{% block hero %}
13-
{% endblock %}
10+
{% include "@components/emergency-alert/emergency-alert.twig" %} {% include
11+
"@components/site-header/site-header.twig" %}
12+
<main id="main-content">
13+
{% block hero %} {% endblock %}
1414
<div class="outer-pad">
15-
{% block subnav %}
16-
{% endblock %}
17-
<div class="page-content">
18-
{% block content %}
19-
{% endblock %}
20-
</div>
15+
{% block subnav %} {% endblock %}
16+
<div class="page-content">{% block content %} {% endblock %}</div>
2117
</div>
22-
{% block end_of_page_call_to_action %}
23-
{% endblock %}
24-
{% include "@components/site-footer/site-footer.twig" %}
18+
{% block end_of_page_call_to_action %} {% endblock %} {% include
19+
"@components/site-footer/site-footer.twig" %}
2520
</main>
2621
</div>
2722
</div>
2823
```
24+
2925
### Usage with Individual Page Templates
26+
3027
Pages will then follow this pattern:
3128

3229
```html
33-
{% extends "@pages/page-structure.twig" %}
34-
{% block hero %}
35-
<!-- Include Hero -->
36-
{% endblock %}
37-
{% block subnav %}
38-
<!-- Include Subnav (if needed, if not - leave blank) -->
39-
{% endblock %}
40-
{% block content %}
41-
<!-- Page Content -->
42-
{% endblock %}
43-
{% block end_of_page_call_to_action %}
44-
<!-- Include End Of Page Call To Action (if needed, if not - leave blank) -->
30+
{% extends "@pages/page-structure.twig" %} {% block hero %}
31+
<!-- Include Hero -->
32+
{% endblock %} {% block subnav %}
33+
<!-- Include Subnav (if needed, if not - leave blank) -->
34+
{% endblock %} {% block content %}
35+
<!-- Page Content -->
36+
{% endblock %} {% block end_of_page_call_to_action %}
37+
<!-- Include End Of Page Call To Action (if needed, if not - leave blank) -->
4538
{% endblock %}
4639
```
4740

4841
### Modifying Page Structure
42+
4943
New blocks can be added as needed to insert different elements per page. For example if a unique site-header and site-footer were needed, `page-structure.twig` could be modified to
5044

5145
```html
5246
<div class="off-canvas">
5347
<div class="max-bound">
54-
{% include "@components/emergency-alert/emergency-alert.twig" %}
55-
{% block header %}{% endblock %}
56-
<main id="main-content">
57-
{% block hero %}
58-
{% endblock %}
48+
{% include "@components/emergency-alert/emergency-alert.twig" %} {% block
49+
header %}{% endblock %}
50+
<main id="main-content">
51+
{% block hero %} {% endblock %}
5952
<div class="outer-pad">
60-
{% block subnav %}
61-
{% endblock %}
62-
<div class="page-content">
63-
{% block content %}
64-
{% endblock %}
65-
</div>
53+
{% block subnav %} {% endblock %}
54+
<div class="page-content">{% block content %} {% endblock %}</div>
6655
</div>
67-
{% block end_of_page_call_to_action %}
68-
{% endblock %}
69-
{% block footer %}{% endblock %}
56+
{% block end_of_page_call_to_action %} {% endblock %} {% block footer %}{%
57+
endblock %}
7058
</main>
7159
</div>
7260
</div>
@@ -75,24 +63,18 @@ New blocks can be added as needed to insert different elements per page. For exa
7563
Usage in the page in this example:
7664

7765
```html
78-
{% extends "@pages/page-structure.twig" %}
79-
{% block header %}
80-
<!-- Include Header -->
81-
{% endblock %}
82-
{% block hero %}
83-
<!-- Include Hero -->
84-
{% endblock %}
85-
{% block subnav %}
86-
<!-- Include Subnav (if needed, if not - leave blank) -->
87-
{% endblock %}
88-
{% block content %}
89-
<!-- Page Content -->
90-
{% endblock %}
91-
{% block end_of_page_call_to_action %}
92-
<!-- Include End Of Page Call To Action (if needed, if not - leave blank) -->
93-
{% endblock %}
94-
{% block footer %}
95-
<!-- Include Footer -->
66+
{% extends "@pages/page-structure.twig" %} {% block header %}
67+
<!-- Include Header -->
68+
{% endblock %} {% block hero %}
69+
<!-- Include Hero -->
70+
{% endblock %} {% block subnav %}
71+
<!-- Include Subnav (if needed, if not - leave blank) -->
72+
{% endblock %} {% block content %}
73+
<!-- Page Content -->
74+
{% endblock %} {% block end_of_page_call_to_action %}
75+
<!-- Include End Of Page Call To Action (if needed, if not - leave blank) -->
76+
{% endblock %} {% block footer %}
77+
<!-- Include Footer -->
9678
{% endblock %}
9779
```
9880

@@ -103,6 +85,7 @@ Usage in the page in this example:
10385
`<div class="outer-pad">` is a direct descendent of the `<main>` tag and is used to match the left and right spacing seen in the design reference (differs per project). The value will typically change according to screen-width and could also change per page template-type.
10486

10587
The inline padding (left and right) custom property values `--outer-padding` can be updated in `base.scss`. The value is changed based on screen width with media queries. One or two values can be used, if two values are used, the first is left padding and the second is right padding. For example:
88+
10689
```scss
10790
// outer padding mobile
10891
--outer-padding: #{rem(30)};
@@ -119,6 +102,7 @@ The inline padding (left and right) custom property values `--outer-padding` can
119102
```
120103

121104
Outer-pad is a placeholder selector (so that it can be re-used) and is applied in **placeholders.scss**:
105+
122106
```scss
123107
%outer-pad {
124108
padding-inline: var(--outer-padding);
@@ -132,6 +116,7 @@ Outer-pad is a placeholder selector (so that it can be re-used) and is applied i
132116
}
133117
}
134118
```
119+
135120
It's applied to `.outer-pad` in **layout.scss**:
136121

137122
```scss
@@ -141,7 +126,9 @@ It's applied to `.outer-pad` in **layout.scss**:
141126
```
142127

143128
### Handling Outer Padding With a Subnav
129+
144130
When a page (ie the [Kitchen Sink](https://staging2.idfive.com/idfive-pattern-lab-starter/public/patterns/pages-kitchen-sink-kitchen-sink/pages-kitchen-sink-kitchen-sink.rendered.html)) has a subnav, the above code `&:has(.subnav)` from **placeholders.scss** sets a grid layout with the subnav as the first column and the main content `<div class="page-content">` as the second column:
131+
145132
```scss
146133
%outer-pad {
147134
&:has(.subnav) {
@@ -165,7 +152,11 @@ Sometimes it's necessary to have a component take up the full width of the page
165152
margin-inline: calc(var(--outer-padding) * -1);
166153
body:has(.subnav) & {
167154
@include mq($min, $lg_desktop) {
168-
margin-inline: calc((var(--outer-pad-subnav-grid-gap) + var(--outer-padding) + var(--outer-pad-subnav-grid-width)) * -1) calc(var(--outer-padding) * -1);
155+
margin-inline: calc(
156+
(
157+
var(--outer-pad-subnav-grid-gap) + var(--outer-padding) + var(--outer-pad-subnav-grid-width)
158+
) * -1
159+
) calc(var(--outer-padding) * -1);
169160
}
170161
}
171162
}

‎docs/front-end/04-twig-templating.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,13 @@ The Pattern Lab Starter uses the twig template language (version 2 - [documentat
1616
```html
1717
{% if hero.image.desktop_src is not empty %}
1818
```
19-
allows us to check if a part of the corresponding data is "not empty" (which can be helpful if a variant is needed so the data can be replicated "empty" as [variants](/docs/front-end/pattern-lab#variants-page--component) pick up the data from their parents)
19+
allows us to check if a part of the corresponding data is "not empty" (which can be helpful if a variant is needed so the data can be replicated "empty" as [variants](/docs/front-end/idfive-component-library#variants-page--component) pick up the data from their parents)
2020
- The subnav is also optional in the hero:
2121
```html
2222
{% if hero.subnav.subnav.items|length > 0 %} {% include
2323
"@components/subnav/subnav.twig" with hero.subnav %} {% endif %}
2424
```
25-
checking if the array has content using the `length` filter is also useful for [variants](/docs/front-end/pattern-lab#variants-page--component) by adding the "empty" array if the intention is to not output the subnav
25+
checking if the array has content using the `length` filter is also useful for [variants](/docs/front-end/idfive-component-library#variants-page--component) by adding the "empty" array if the intention is to not output the subnav
2626

2727
## For Loop
2828

‎docs/general/accessibility.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -154,7 +154,7 @@ Automated tools catch many issues, but human testing is essential:
154154

155155
### Component Library Accessibility Features
156156

157-
Our [idfive Component Library (ICL)](/docs/front-end/pattern-lab) includes built-in accessibility features:
157+
Our [idfive Component Library (ICL)](/docs/front-end/idfive-component-library) includes built-in accessibility features:
158158

159159
#### JavaScript Utilities
160160

@@ -316,4 +316,4 @@ Our goal is to make the web more accessible, one project at a time. Whether you'
316316

317317
---
318318

319-
_For technical implementation details, developers can reference our [Front-end Accessibility Guidelines](/docs/front-end/accessibility) and [Component Library documentation](/docs/front-end/pattern-lab)._
319+
_For technical implementation details, developers can reference our [Front-end Accessibility Guidelines](/docs/front-end/accessibility) and [Component Library documentation](/docs/front-end/idfive-component-library)._

0 commit comments

Comments
 (0)