diff --git a/docs/getting-started/first-project.md b/docs/getting-started/first-project.md new file mode 100644 index 0000000..dfd3675 --- /dev/null +++ b/docs/getting-started/first-project.md @@ -0,0 +1,327 @@ +--- +id: first-project +title: Your First Project +--- + +Welcome to SCSS Starter. + +This tutorial introduces you to the essentials of SCSS Starter by walking you through building a simple card. + +> New To Web Development?

+> There are many resources to complement the SCSS Starter docs. Mozilla's MDN docs includes comprehensive [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) documentation and Get BEM docs includes an introduction to [BEM](http://getbem.com/introduction/). + +## Setup + +To get started with SCSS Starter please read the [download](download.md) documentation. In order to start, please copy the `scss` folder into your own development environment. + +> The methods we mention in this documentation are based on [Atölye15](https://www.atolye15.com/)'s own experiences over the years. These methods are rather obligations but more of suggestions. You may follow your own ways. + +## Setting Up Global Variables + +You need to set up your global variables prior to starting the project based on your design's needs. + +### Colors + +> Please refer to [colors](core/colors.md) page for further explanation. + +In order to create your card component, you should start by adding the colors to your `abstracts/_colors.scss` file. + +1. Set the primary color variable. + +```scss +$color-palette-primary: ( + 50: #e8eaf6, + 100: #c5cae9, + 200: #9fa8da, + 300: #7986cb, + 400: #5c6bc0, + 500: #3f51b5, + 600: #3949ab, + 700: #303f9f, + 800: #283593, + 900: #1a237e, +); +``` + +2. To make the newly set color palette available, you need to use `color-palette` function. For that add `$color-palette-primary` map variable into `$g-color-palettes` map variable. + +```scss +$g-color-palettes: ( + 'gray': $color-palette-gray, + 'primary': $color-palette-primary, +); +``` + +3. You can now set the global color settings based on the project's needs. + +```scss +$g-body-bg: color-palette('gray', 50) !default; +``` + +### Typography + +#### Adding Fonts + +To add a different font file to your project you should use `font-face` mixin in `base/_fonts.scss` file. + +```scss +@include font-face('Roboto', 'Roboto', 'Roboto-Medium', 500); +@include font-face('Roboto', 'Roboto', 'Roboto-MediumItalic', 500, italic); +``` + +#### Setting Variables + +1. Set your font family variable by equaling your font name to `$g-font-family-primary` variable. Then add `$g-font-family-primary` variable to `$g-font-family-sans-serif` as the first value. + +```scss +$g-font-family-primary: 'Roboto'; +$g-font-family-sans-serif: $g-font-family-primary, 'Helvetica Neue', Helvetica, Arial, sans-serif !default; +``` + +> The `$g-font-family-sans-serif` variable sets body's font family. + +2. Font sizes are customizable but for the sake of example, we are choosing not to. + +```scss +$g-font-size-h1: px-to-rem(36px) !default; +$g-font-size-h2: px-to-rem(30px) !default; +$g-font-size-h3: px-to-rem(24px) !default; +$g-font-size-h4: px-to-rem(18px) !default; +$g-font-size-h5: 1rem !default; +$g-font-size-h6: px-to-rem(14px) !default; +``` + +3. Other heading variables are also customizable. + +```scss +$g-headings-font-family: inherit !default; +$g-headings-font-weight: 500 !default; +$g-headings-line-height: 1.1 !default; +$g-headings-margin-bottom: 1rem !default; +``` + +> Headings and other HTML elements can be customized on `base/_base.scss` file. (For example: You can use customization as shown here to set different line-height values for each heading tags. ) + +4. Global margin(`$g-gaps`) and padding(`$g-pads`) variables can be customized or increased based on the design's needs. (2xlarge value is added to the map.) + +```scss +$g-gaps: ( + normal: $g-base-gap, + small: ( + $g-base-gap / 1.5, + ), + xsmall: ( + $g-base-gap / 3, + ), + 2xsmall: ( + $g-base-gap / 6, + ), + medium: ( + $g-base-gap * (4 / 3), + ), + large: ( + $g-base-gap * (5 / 3), + ), + xlarge: ( + $g-base-gap * 2, + ), + 2xlarge: ( + $g-base-gap * 4, + ), +); +``` + +> When adding a new margin or padding value, please ensure that it's a children of `$g-base-gap` variable. + +## Creating A Component + +Start developing components after setting up the global variables. + +> The following steps use predefined card component from the `c-card.scss` file. + +1. Create a folder `c-card` in the components folder and open the scss file `c-card.scss`. +2. Develop the card component as shown below. + +```html +
+
+ This is a header +
+ Placeholder +
+

This is a card.

+

+ Lorem ipsum dolor sit amet consectetur, adipisicing elit. Earum eveniet illum aut harum ullam + dolore repudiandae pariatur optio exercitationem. +

+
+
+``` + +> Since we don't want the tags on **card content** element to be dependent to **the card component**, we have cleared default margins of `h4` and `p` tags by using utility classes. On the case of not using utility classes; we would need to add `c-card__title` class to `h4` element and `c-card__text` class to `p` element. + +> By using utility classes there would be no need of creating new class names and it helps the construction to be more flexible. + +```scss +.c-card { + background-color: $color-white; + border-radius: px-to-rem(4px); + box-shadow: px-to-rem(2px) px-to-rem(2px) px-to-rem(16px) rgba($color-black, 0.4); + + &__header { + padding: pad(xsmall); + border-bottom: 1px solid color-palette('gray', 100); + } + + &__image { + width: 100%; + height: auto; + } + + &__content { + padding: pad(xsmall); + } +} +``` + +Result: + +
+
+
+ This is a header +
+ +
+

This is a card.

+

Lorem ipsum dolor sit amet consectetur, adipisicing elit. Earum eveniet illum aut harum ullam dolore repudiandae pariatur optio exercitationem.

+
+
+
+ +## Grid Layout In Action + +The developed component can be used on the page along with the grid layout. + +```html +
+
+
+
+
...
+
+
+
...
+
+
+
...
+
+
+
+
+``` + +
+
+
+
+
+
+ This is a header +
+ +
+

This is a card.

+

+ Lorem ipsum dolor sit amet consectetur, adipisicing elit. Earum eveniet illum aut + harum ullam dolore repudiandae pariatur optio exercitationem. +

+
+
+
+
+
+
+ This is a header +
+ +
+

This is a card.

+

+ Lorem ipsum dolor sit amet consectetur, adipisicing elit. Earum eveniet illum aut + harum ullam dolore repudiandae pariatur optio exercitationem. +

+
+
+
+
+
+
+ This is a header +
+ +
+

This is a card.

+

+ Lorem ipsum dolor sit amet consectetur, adipisicing elit. Earum eveniet illum aut + harum ullam dolore repudiandae pariatur optio exercitationem. +

+
+
+
+
+
+
+ +> Please refer to [responsive utilities](utilities/responsive.md) page for learning more about responsive utilities. And refer to [grid](layout/grid.md) page for the grid system usage. + +## Making A Component Responsive + +The component has been made responsive by adding responsive functions to the component layer. + +```scss +.c-card { + background-color: $color-white; + border-radius: px-to-rem(4px); + box-shadow: px-to-rem(2px) px-to-rem(2px) px-to-rem(16px) rgba($color-black, 0.4); + + @include media-brekpoint-down(md) { + display: flex; + flex-direction: row; + } + + &__header { + padding: pad(xsmall); + border-bottom: 1px solid color-palette('gray', 100); + + @include media-breakpoint-down(md) { + display: none; + } + } + + &__image { + width: 100%; + height: auto; + } + + &__content { + padding: pad(xsmall); + } +} +``` + +
+
+ This is a header +
+ +
+

This is a card.

+

+ Lorem ipsum dolor sit amet consectetur, adipisicing elit. Earum eveniet illum aut + harum ullam dolore repudiandae pariatur optio exercitationem. +

+
+
+ +> Please refer to [breakpoint](core/mixins.md#breakpoint) section on the mixins page for learning more about responsive mixins. diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md index 9b35e62..c102fa2 100644 --- a/docs/getting-started/introduction.md +++ b/docs/getting-started/introduction.md @@ -20,8 +20,8 @@ Because; - It has well designed [architecture](getting-started/architecture.md). - It has supportive mixins & functions. - Every part of SCSS Starter can be customized based on your project's needs including variables, utilities, a grid system, etc. -- It is extremely easy to build responsive interfaces without extra effort. All utility classes and a grid system can be extended with responsive variants. --SCSS Starter doesn't conflict with your own styles, because it doesn't have any styles other than the basics. +- It is extremely easy to build responsive interfaces without extra effort. All utility classes and the grid system can be extended with responsive variants. +- SCSS Starter doesn't conflict with your own styles, because it doesn't have any styles other than the basics. - Utilities, mixins and functions can be extended if needed. ## Browser Support diff --git a/website/i18n/en.json b/website/i18n/en.json index 81c6c89..d43911a 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -23,6 +23,9 @@ "getting-started/download": { "title": "Download" }, + "getting-started/first-project": { + "title": "Your First Project" + }, "getting-started/introduction": { "title": "Introduction" }, diff --git a/website/sidebars.json b/website/sidebars.json index eb16d09..b1693c7 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -1,11 +1,12 @@ { "docs": { - "Core": ["core/colors", "core/variables", "core/mixins", "core/functions"], "Getting Started": [ "getting-started/introduction", + "getting-started/architecture", "getting-started/download", - "getting-started/architecture" + "getting-started/first-project" ], + "Core": ["core/colors", "core/variables", "core/mixins", "core/functions"], "Layout": ["layout/grid"], "Utilities": ["utilities/predefined-classes", "utilities/responsive", "utilities/customizing"] } diff --git a/website/src/styles/custom.scss b/website/src/styles/custom.scss index 8efb2b1..8906205 100644 --- a/website/src/styles/custom.scss +++ b/website/src/styles/custom.scss @@ -72,6 +72,57 @@ background-color: #e6e6e6; } +.layout { + width: 16.875rem; + margin-bottom: 1rem; + + @include media-breakpoint-down(md) { + width: auto; + } +} + +.c-example-card { + background-color: $color-white; + border-radius: 0.25rem; + box-shadow: 0.125rem 0.125rem 1rem rgba($color-black, 0.1); + + @include media-breakpoint-down(md) { + display: flex; + flex-direction: row; + margin-top: gap(); + } +} + +.c-example-card--mobile { + display: flex; + flex-direction: row; + margin-top: gap(); + margin-bottom: gap(); +} + +.c-example-card__header { + padding: pad(xsmall); + border-bottom: 1px solid color-palette('gray', 100); + + @include media-breakpoint-down(md) { + display: none; + } +} + +.c-example-card--mobile .c-example-card__header { + display: none; +} + +.c-example-card__image { + width: 100%; + height: 12.5rem; + object-fit: cover; +} + +.c-example-card__content { + padding: pad(xsmall); +} + // @media only screen and (min-device-width: 360px) and (max-device-width: 736px) { // }