8 Thực tiễn Tốt nhất về Tài liệu CSS hoàn hảo

Trong thế giới của CSS, documentation (tài liệu) không được tận dung. Do documentation không thấy được từ phía người dùng nên giá trị của documentation thường bị khách hàng bỏ qua. Ngoài ra, nếu đây là lần đầu tiên bạn làm tài liệu lại cho code, có thể khó xác định điều gì cần làm tài liệu và làm sao để thực hiện hiệu quả nhất.

Tuy nhiên, làm tài liệu về CSS có thể mang lại rất nhiều ích lợi cho dự án của bạn: từ việc khuyến khích thực hành code tốt hơn để giảm bớt việc vận hành cho những thành viên mới của nhóm. Trong bài viết này, tôi sẽ giải thích các lợi thế của việc làm tài liệu CSS và chia sẻ những điều nhóm của tôi và tôi tại Bitovi cân nhắc là những thực tiễn tốt nhất để làm tài liệu hướng dẫn cho bạn chứ không phải theo hướng ngược lại. Hãy nghiên cứu nó nào.

1. Thiết lập các quy tắc cơ bản

Thật khó để thực hiện trào lưu làm tài liệu khi bạn và nhóm của bạn không rõ về nó: những gì phải làm tài liệu hoặc làm bạn muốn nó hoạt động như thế nào. Vì vậy, bước đầu tiên là đồng ý các quy ước bạn sẽ sử dụng và cách bạn nên triển khai chúng. Bạn có thể làm điều này trong một tài liệu trực tuyến để mọi người trong nhóm có thể cùng đóng góp. Với cách này, khi cách tiếp cận của bạn thay đổi hoặc trở nên toàn diện hơn, bạn luôn có thể cập nhật nó. Tài liệu Google được chia sẻ, một trang wiki trên code repo của bạn hoặc (thậm chí tốt hơn) một trang về "hướng dẫn style sinh động" của bạn là tất cả những nơi tuyệt vời cho việc này.

Bây giờ chúng ta hãy xem xét các "quy tắc cơ bản" thực sự mà bạn có thể đưa vào.

2. Giải thích cấu trúc của code base

Việc hiểu được code base của bạn được tổ chức như thế nào cho phép bất kỳ ai bắt tay vào hành động ngay ngày đầu tiên. Một cách đơn giản để làm điều này là tạo ra một bản đồ về cấu trúc file của bạn, ở đó bạn có thể giải thích những gì bên trong và chúng nên như thế nào. Khi làm việc này, hãy đặc biệt chú ý đến những chỗ có thể không rõ ràng. Ví dụ, chỉ ra rằng file "button.css" gồm các style cho các button không thực hữu ích, thay vào đó chỉ ra rằng thư mục custom là nơi những style tùy biến cho giao diện được lưu lại có thể giúp tiết kiệm thời gian hơn.

Đây là một ví dụ:

1

Project Root

2

 └── srs

3

     ├── styles               // Base styles. Styles placed here should be available anywhere in the application     

4

         ├── bootstrap-custom // Custom styles that overwrite bootstrap

5

         ├── custom           // Custom styles created for the application

6

         ├── demos            // Demos to illustrate styles and interactions for the style guide

7

         ├── fonts           

8

         ├── img              // Images used ONLY in stylesheets

9

         ├── variables        // Variables used in the custom theme

10

         └── styles.less      // Imports of all the base stylesheets

11

12

     └── components

13

         ├── alerts       

14

             └── alert.less   // Custom styles for the alert component. Every component has its own stylesheet that allows to customize it specifically preventing bloat and style leaking.

Theo nguyên tắc chung, hãy ghi lại những nơi cần sự rõ ràng. Không phải cho mọi thư mục và file sẽ cần làm tài liệu (như trong ví dụ trên "fonts" đã rõ ràng không cần giải thích thêm). Đặt mình vào vị trí của người mới tham gia dự án (hoặc nhớ lại những lúc bạn ở vị trí của họ) và cung cấp hướng dẫn bạn từng muốn bạn nên nhận được. Ý tưởng là thực hiện điều này theo cách không tốn nhiều thời gian của bạn nhưng lại hữu ích và tránh được những câu hỏi lặp đi lặp lại.

Một yếu tố chính cần chỉ ra ở đây là những style mới nên được bổ sung ở đâu và các bước bất kỳ sau đó cần được tuân thủ. Ví dụ trên chứng minh điều này, nhưng với bản chất thừa kế của CSS, rất cần thiết để xác định chi tiết hơn.

Ví dụ: trong các dự án mà chúng tôi đã sử dụng Bootstrap làm framework cơ sở, chúng tôi thường có ba vị trí nơi cần đặt các quy tắc mới, tùy thuộc vào những gì nhà phát triển đang cố gắng đạt được. Vì vậy, chúng tôi đã bổ sung một hướng dẫn cho tài liệu bao gồm ba tình huống:

Tình huống #1

Nếu bạn muốn overwrite lên style được định nghĩa bởi Bootstrap, sau đó:

1. Tìm hiểu xem stylesheet nào của bootstrap là quy tắc đã được định nghĩa.
2. Đi đến file "src/styles/bootstrap-custom".
3. Tìm kiếm stylesheet tương tự.
4. Nếu file đó không tồn tại, hãy tạo một file mới đặt tên giống vậy ở trong thư mục đó.
5. Bổ sung phần overwrite của bạn và chỉ ra điềuì quan trọng bất kỳ.
6. Cuối cùng, nhập stylesheet mới vào trong "src/styles/style.less".

Tình huống 2

Nếu bạn muốn bổ sung một định nghĩa style mới mà không ghi đè lên Bootstrap và nó có thể truy xuất ở bất cứ đâu trong ứng dụng, vậy thì:

1. Đi đến thư mục "src/styles/custom".
2. Tìm một stylesheet có thể thêm style mới (nghĩ xem: đây có phải là style để định nghĩa một nút, hay là một style có thể có thể sử dụng lại được như một mixin?) Và đặt nó vào nơi nó có ý nghĩa nhất.
3. Nếu không có một stylesheet có lý để đặt style mới này, vậy hãy tạo ra một stylesheet mới.
4. Đặt tên nó theo các quy ước đặt tên của chúng ta.
5. Thêm style của bạn và chỉ ra bất cứ điều gì quan trọng.
6. Cuối cùng, nhập style mới vào trong "src/styles/style.less".

Tình huống #3

Nếu bạn muốn bổ sung một định nghĩa style mới cho một thành phần (điều này có nghĩa là nó sẽ có hiệu lực chỉ với thành phần đó, dù thành phần đó được sử dụng ở đâu trong ứng dụng), vậy thì:

1. Đến thư mục "src/components".
2. Tìm thành phần bạn muốn tạo kiểu.
3. Tìm stylesheet cho thành phần, bên trong thư mục của thành phần đó.
4. Cuối cùng, thêm style mới và chỉ ra điều gì quan trọng.

Hướng dẫn này:

• Giúp cho các style của chúng tôi được ngăn nắp.
• Giúp các style hoạt động theo kế thừa mà chúng tôi đã thiết lập vì những phần thay thế đã được thực hiện ở đúng nơi.
• Tránh các nhà phát triển đề ra các quy tắc quá phức tạp.
• Phòng tránh style gây ảnh hưởng đến những thành phần không liên quan.

3. Thiết lập tiêu chuẩn xây dựng mã của bạn

Tiêu chuẩn các code của bạn hoặc hướng dẫn về CSS đề cập đến cách mà nhóm của bạn đã đồng ý trong việc xây dựng CSS. Điều này bao gồm các thực hành nhất về viết code, như định dạng, đặt tên, và các quy ước cú pháp. Nhiều công ty đã chia sẻ cách họ làm điều này (bài viết này từ CSS-Tricks có một bản biên dịch tuyệt vời: CSS Style Guides). Dưới đây là một vài cách tôi thấy hữu ích khi chia sẻ loại thông tin này:

Danh sách điều nên làm và không nên làm

Sử dụng định dạng này để chỉ ra những điều mà bạn muốn tránh, trong khi cung cấp một sự thay thế khả thi. Điều này loại bỏ sự mơ hồ và khuyến khích mọi người làm một việc cụ thể. Ví dụ:

Danh sách các thực hành tốt nhất

Tóm tắt các nguyên tắc của bạn thành những thực tiễn tốt nhất và bao gồm các ví dụ. Điều này sẽ làm cho mỗi thứ dễ dàng hơn khi đọc và hiểu. Ví dụ:

Mỗi nhà phát triển viết code rất khác nhau. Đó là lý do tại sao đội nhóm của bạn cần thiết lập các tiêu chuẩn về code. Điều này đảm bảo rằng code trở nên nhất quán trong một dự án, giúp bạn đọc, viết và xem lại dễ dàng hơn. Nhưng đảm bảo rằng bất cứ điều gì bạn đưa vào coding standard (tiêu chuẩn code) của bạn là một thực tế mà nhóm của bạn đã đồng ý.

Tôi đã làm việc cho một dự án mà chúng tôi đưa vào style guide hiện có của chúng tôi. Là một phần của code, chúng tôi cam kết và đưa những thực tiễn tốt nhất vào repo. Sau đó, để đảm bảo tất cả mọi người đều hiểu, tất cả mọi người trong nhóm phải chấp thuận yêu cầu pull trước khi chúng tôi có thể merge (hợp nhất). Điều này đảm bảo rằng mọi người phải dành thời gian để xem xét và thảo luận về nó.

4. Tránh các Stylesheets dài dòng

Khi bạn chia nhỏ stylesheet của bạn thành các stylesheet nhỏ hơn và tập trung hơn, bạn sẽ dễ dàng document chúng hơn. Bạn cũng có thể tiết kiệm thời gian bằng cách không phải document những kiểu có tính tự giải thích.

Ví dụ, thay vì có một stylesheet dài dòng 800 với tất cả các biến mà bạn có thể sử dụng trong một giao diện, bạn có thể có một file cho từng loại biến. Điều này sẽ tiết kiệm thời gian khi không phải di chuyển lên và xuống trong file để cố gắng tìm một kiểu nào đó! Nghĩ đến thời gian mà bạn có thể tiết kiệm bằng cách không phải cập nhật index mỗi khi bạn thêm hoặc đổi tên một phần mới.

Trong một tập tin dài, một index (chỉ mục) dài ...

1

/*-------------------------------------------*\

2

    variables.less

3

4

    Index

5

    - Color Palette

6

    - Typography

7

    - Buttons

8

    - Forms

9

    - Layout

10

    - Messaging & Status

11

    - General

12

    - Navigation

13

    - Carousel

14

    - Jumbotron

15

 \*-------------------------------------------*/

Chia nhỏ một file, không có chỉ mục nào cần thiết:

Một ví dụ khác để cân nhắc khi làm việc trong các ứng dụng lớn là modlet workflow (quy trình modlet). Điều này giải thích tại sao làm việc với các file nhỏ hơn được tổ chức bởi các thành phần cho phép kiểm tra và gộp chung chúng trong ứng dụng của bạn dễ dàng hơn.

5. Luôn tạo tài liệu CSS với một style guide

Một phần lớn của việc làm tài liệu CSS đúng cách có liên quan đến việc viết CSS tốt và ngược lại. Điều này có nghĩa là cả khi trạng thái của code cơ sở CSS của bạn có thể không phải tốt nhất, thì việc thực thi các quy tắc tài liệu có thể giúp bạn tiến tới một hệ thống tốt hơn.

Đây là nơi mà việc cung cấp tài liệu CSS với một style guide cần ghi nhớ xuất hiện. Ý tưởng đằng sau nó là một style guide có thể giúp lập cấu trúc tốt cho CSS, bạn sẽ cần phải phân biệt giữa:

• các style cơ sở định nghĩa giao diện của ứng dụng (bao gồm bất kỳ framework CSS nào mà bạn đang sử dụng)
• các thay đổi tuỳ biến được thực hiện cho các thành phần cụ thể, và
• các thay đổi tuỳ biến được thực hiện cho các trang cụ thể.

Phần lớn CSS của bạn nên bao gồm các style cơ sờ nền tảng, vì chúng hiện hữu ở bất kỳ đâu trong ứng dụng và ảnh hưởng đến tất cả các phần tử với trạng thái mặc định của chúng. Các style tuỳ biến sẽ xuất hiện khi bạn bổ sung các thành phần với một giao diện và hành vi cụ thể hoặc trong trường hợp bố cục của một phần tử hoặc thành phần trong một trang yêu cầu.

Một cách tuyệt vời để nắm bắt cách thiết lập cụ thể này có thể hoạt động trong ứng dụng của bạn là create a style guide sitemap (tạo một sơ đồ trang hướng dẫn về style ). Một khi bạn đã biết một style guide sẽ ra sao trong ứng dụng của bạn, bạn có thể chú ý để làm tài liệu các thành phần đó. Ví dụ: nếu bạn đã xác định trong style guide những buttons và navigations (mục điều hướng) trông như thế nào, rõ ràng bạn nên thêm các style và documentation mới cho chúng (trong "buttons.css" và "navs.css"). Nhưng một navigation được xây dựng từ các button thì sao?

Có một style guide có thể giúp bạn đưa ra quyết định này, vì bạn có thể so sánh các button và navigation trông như thế nào, từ màn hình hiển thị và khía cạnh markup. Hãy xem ví dụ này:

1

<button type="button" class="btn btn-primary">Primary</button>

2

 <button type="button" class="btn btn-secondary">Secondary</button>

3

 <button type="button" class="btn btn-emphasis">Emphasis</button>

4

5

 <button type="button" class="btn btn-primary disabled">Primary</button>

6

 <button type="button" class="btn btn-secondary disabled">Secondary</button>

7

 <button type="button" class="btn btn-emphasis disabled">Emphasis</button>

1

<ul class="nav nav-tabs">

2

      <li class="active"><a href="#">Active</a></li>

3

      <li><a href="#">Nav Item</a></li>

4

      <li><a href="#">Nav Item</a></li>

5

      <li class="disabled"><a href="#">Nav Item</a></li>

6

 </ul>

Trong trường hợp này, có hai vị trí có thể cho CSS sẽ đinh nghĩa navigation được tạo ra từ buttons:

1. Nếu markup tuân theo theo cấu trúc các phần navigation khác, sử dụng một danh sách liên kết, hoặc một thẻ <nav> với các liên kết trông giống như các button, sau đó thêm các style cho nav trong "navs.css"
2. Nếu markup mà bạn sẽ sử dụng là <button> sau đó, thêm phong cách vào "buttons.css". Bạn thậm chí có thể thêm nó như một stylesheet riêng biệt (như "buttons-group.css"). Trong trường hợp này, thuật ngữ "navigation" sẽ không thích hợp nữa vì các button HTML không thể truy cập như các mục navigation.

6. Phân nhỏ stylesheets của bạn

Một khi bạn đã chia nhỏ stylesheet của bạn thành các file dễ quản lý hơn, thì bạn có thể tiếp tục bài tập này bằng cách chia nhỏ từng style thành các thành phần riêng lẻ nhỏ hơn.

Để bắt đầu, mỗi stylesheet ít nhất phải bao gồm tiêu đề và (khi hữu ích) một mô tả ngắn. Tiêu đề có thể đơn giản như tên file, được viết hoa để trông giống như một tiêu đề (ví dụ: "Buttons" cho stylesheet "buttons.css"), hoặc nó có thể giống với tên của file, giống như vậy:

1

/**

2

  * icons.css

3

  */

4

5

 .icon {

6

   font-family: 'bitovi';

7

   speak: none;

8

   font-style: normal;

9

   font-weight: normal;

10

   font-variant: normal;

11

   text-transform: none;

12

   line-height: 1;

13

 }

14

Tôi nhận ra việc sử dụng tên file đặc biệt hữu ích khi sửa lỗi code trong trình duyệt, và chủ yếu là khi tập tin đã được biên dịch cùng với các tập tin khác, khi tôi có thể tham chiếu đến file chứa style nào đó.

Ngoài ra, lưu ý rằng style của comment mà tôi sử dụng mở đầu với /** vs thay vì /*. Đây là quy ước được sử dụng trong JSDoc để phân tích các comment, chúng có thể có trong document phát sinh tự động. Tôi khuyên bạn nên sử dụng style này, vì nhiều trình tự tạo style guide hiện thời sử dụng định dạng JSDoc, vì vậy khi bạn đã sẵn sàng sử dụng máy phát điện, mã của bạn sẽ không tạo thêm quá nhiều công việc.

Bất kỳ trường hợp nào, bạn có thể sử dụng các style khác để biểu thị một phần chẳng hạn như:

1

/*-------------------------------------------*\

2

     icons.css

3

 \*-------------------------------------------*/

4

5

 .icon {

6

   font-family: 'bitovi';

7

   speak: none;

8

   font-style: normal;

9

   font-weight: normal;

10

   font-variant: normal;

11

   text-transform: none;

12

   line-height: 1;

13

 }

14

Ở một mức độ nào đó, điều này phụ thuộc vào đội nhóm của bạn đồng ý điều gì tốt nhất để làm một phần trở thành nổi bật. Yêu cầu duy nhất là sử dụng /* ở đầu và */ ở cuối. Điều thực sự quan trọng là bất cứ cách tiếp cận nào bạn sử dụng, thì bạn bám chặt vào nó và sử dụng nó trên code CSS của bạn theo một cách nhất quán.

Nếu bạn nghĩ một mô tả có thể hữu ích trong một stylesheet cụ thể, sau đó thêm nó như là một phần của comment đầu tiên này. Ví dụ:

1

/**

2

  * icons.css

3

  *

4

  * Icons should convey in a simple and meaningful way the concept of the function

5

  * they represent. When designing new icons be sure to remove any complexities 

6

  * and follow the linear and lightweight appearance of the icon set.

7

  */

8

9

 .icon {

10

   font-family: 'bitovi';

11

   speak: none;

12

   font-style: normal;

13

   font-weight: normal;

14

   font-variant: normal;

15

   text-transform: none;

16

   line-height: 1;

17

 }

Làm điều này sẽ củng cố ý tưởng của của việc nó là một thành phần. Ngoài ra, cố gắng chia mô tả thành nhiều dòng (Harry Roberts đề xuất lên đến 80 ký tự) để nó dễ đọc hơn khi ta mở nhiều file hoặc xem ở trên Github.

Sau khi thêm tiêu đề và mô tả, bạn có thể tiến thêm một bước nữa bằng cách chia nhỏ các style trong stylesheet thành các phần nhỏ. Để làm điều này suy nghĩ về cách giải thích hợp lý các nội dung của một stylesheet có ý nghĩa. Ví dụ: stylesheet "buttons.css" thường sẽ có một phần mà style mặc định của button được xác định bằng cách chỉ áp dụng class .btn. Sau đó, sẽ có thêm các style để định nghĩa màu sắc, kích cỡ và cấu hình khác nhau có thể được áp dụng kết hợp để tuỳ chỉnh thêm sự xuất hiện và hành vi của nó. Tạo các phần cho các style này sẽ làm cho nó dễ hiểu hơn và tìm nơi mà các class mới hoặc phần overwrite sẽ xuất hiện. Ngoài ra, cũng ít khắt khe hơn khi mà code được trình bày trong các đoạn code so với một file dài đến mức thật khó để nói rằng nơi nào style bắt đầu và kết thúc.

Hãy xem ví dụ mang tính so sánh này. Đầu tiên, môt đoạn code của LESS không chưa các thành phần:

1

.label-condensed-variant(@color) {

2

   &:before {

3

     background-color: @color;

4

   }

5

 }

6

7

 .label {

8

   border-radius: 0;

9

   font-family: @font-family-bold;

10

   font-size: 85%;

11

   position: relative;

12

   &.label--condensed {

13

     font-size: @font-size-xsmall;

14

     color: @gray;

15

     background: transparent;

16

     padding-right: @padding-small;

17

     &.label--primary {

18

       .label-condensed-variant(@label-primary-bg);

19

     }

20

     &.label--success {

21

       .label-condensed-variant(@label-success-bg);

22

     }

23

     &.label--info {

24

       .label-condensed-variant(@label-info-bg);

25

     }

26

     &.label-warning {

27

       .label--condensed-variant(@label-warning-bg);

28

     }

29

     &.label--danger {

30

       .label-condensed-variant(@label-danger-bg);

31

     }    

32

   }

33

   &.label--simple {

34

     font-family: @font-family-base;

35

     font-size: @font-size-xsmall - 1;

36

     color: @gray;

37

     border: 1px solid @gray-light;

38

     padding: 2px;

39

     border-radius: @border-radius-small;

40

     text-transform: uppercase;

41

   }

42

 }

Và cùng một đoạn code với các thành phần:

1

/**

2

  * bootstrap-custom/_labels.less Labels

3

  * 

4

  * Overwrites the default styles defined by the bootstrap framework.

5

  *

6

  */

7

8

 .label {

9

   border-radius: 0;

10

   font-family: @font-family-bold;

11

   font-size: 85%;

12

   position: relative;

13

 }

14

15

16

 /**

17

  * Condensed Labels

18

  *

19

  * Modifies labels to provide a smaller and narrower version with a colored circle to be used in areas with little space (for example in list views).

20

  */

21

22

 .label {

23

   &.label--condensed {

24

     font-size: @font-size-xsmall;

25

     color: @gray;

26

     background: transparent;

27

     padding-right: @padding-small;    

28

   }

29

 }

30

31

32

 /**

33

  * Condensed Labels - Colors

34

  */

35

36

 .label-condensed-variant(@color) { // Variant mixin to set the circle color

37

   &:before {

38

     background-color: @color;

39

   }

40

 }

41

42

 .label {

43

   &.label--condensed {

44

     &.label--primary {

45

       .label-condensed-variant(@label-primary-bg);

46

     }

47

     &.label--success {

48

       .label-condensed-variant(@label-success-bg);

49

     }

50

     &.label--info {

51

       .label-condensed-variant(@label-info-bg);

52

     }

53

     &.label--warning {

54

       .label-condensed-variant(@label-warning-bg);

55

     }

56

     &.label--danger {

57

       .label-condensed-variant(@label-danger-bg);

58

     }

59

   }

60

 }

61

62

63

 /**

64

  * Simple Labels

65

  *

66

  * Modifies labels to provide a simple linear version where colors are not used.

67

  */

68

69

 .label {

70

   &.label--simple {

71

     font-family: @font-family-base;

72

     font-size: @font-size-xsmall - 1;

73

     color: @gray;

74

     border: 1px solid @gray-light;

75

     padding: @padding-small;

76

     border-radius: @border-radius-small;

77

     text-transform: uppercase;

78

   }

79

 }

7. Chỉ mục Các nội dung trong Stylesheets của bạn

Đây là một cách tuyệt vời để cung cấp một cái nhìn tổng quan về những gì trong stylesheet và những điều cần thiết trong những dự án đó, với bất kỳ lý do nào, các stylesheet dài đang ở đó (không phải là fan của những dự án đó, nhưng chúng lại xảy ra!).

Một chỉ mục stylesheet thường như sau:

1

/**

2

  * icons.css

3

  *

4

  * Icons should convey in a simple and meaningful way the concept of the function

5

  * they represent. When designing new icons be sure to remove any complexities 

6

  * and follow the linear and lightweight appearance of the icon set.

7

  *

8

  * Index

9

  * - Icon Font

10

  * - Icon Variations

11

  * - Icon Animations

12

  *

13

  */

Và mặc dù tôi thích cách gọn gàng và hữu ích của chúng, chúng tôi phải thừa nhận rằng chúng có thể dễ dàng bị bỏ quên, và do đó đã lỗi thời. Thật khó khăn để cập nhật khi chúng quá dài và bạn đang sử dụng những con số (vì thế hãy tránh những điều này!)

Một cách khác để sử dụng các index là để cho một trình phát sinh style guide thực hiện công việc cho bạn bằng việc xem stylesheet của bạn, tìm các phần mà bạn đã xác định và tạo một chỉ mục cho bạn. Tôi sẽ mở rộng thêm về chủ đề này ở phần cuối của bài viết này.

8. Tìm điểm trọng tâm của việc làm tài liệu

Đây là nơi bí mật của tài liệu. Rất dễ bị cuốn hút và đào sâu vào một tài liệu trong một lần, rồi sau đó quên mất nó và nhận ra rằng chỉ một phần của code cơ sở của bạn được làm tài liệu quá nhiều và phần còn lại không được làm tài liệu gì cả. Giống như mọi thứ trong cuộc sống, bí mật là tìm kiếm sự cân bằng. Ghi lại các chỗ cần chú ý bởi vì sẽ có sự lệ thuộc không thấy trước được, những tài nguyên bổ sung hoặc các ghi chú quan trọng cần lưu ý. Điều đó nói rằng không phải tất cả mỗi bit của code đều được ghi lại nhưng chắc chắn sẽ hữu ích để chia chúng thành các đoạn nhỏ và giải thích những gì những đoạn mã đó là gì khi cần thiết. Bằng cách này, tài liệu trở thành một công cụ hữu ích, là một phần của quy trình làm việc của bạn và không phải là một suy nghĩ mà bạn tránh làm. Nhưng làm điều này chính xác như thế nào? Đây là một ví dụ:

Giả sử bạn dự đình triển khai các markup và CSS cho các thành phần card sau đây:

Nhìn vào thiết kế, bạn có thể định nghĩa các kiểu mẫu sau:

• Thiết kế card cơ bản
• Grid cho các card
• Danh sách card
• Phiên bản card màu tối

Sau đó, bạn có thể chia nhỏ việc triển khai CSS với những pattern đó và sử dụng tài liệu hướng dẫn bạn. Để bắt đầu, stylesheet "cards.css" của bạn có thể gồm một giới thiệu đơn giản như sau:

1

/**

2

  * cards.css

3

  *

4

  * These are the styles for the card component.

5

  *

6

  * Index

7

  * - Card Base 

8

  * - Card Grid

9

  * - Card List

10

  * - Card Dark

11

  */

12

Bạn có thể thêm thông tin hữu ích vào phần giới thiệu, nhưng khi bạn bắt đầu, một cái gì đó đơn giản có thể giúp bạn xây dựng cấu trúc của tài liệu.

Sau đó, hãy bổ sung các phần mà bạn sẽ làm việc theo style của bạn:

1

/**

2

  * cards.css

3

  *

4

  * These are the styles for the card component.

5

  *

6

  * Index

7

  * - Card Base 

8

  * - Card Grid

9

  * - Card List

10

  * - Card Dark

11

  */

12

13

14

 /**

15

  * Card Base

16

  */

17

18

19

 /**

20

  * Card Grid

21

  */

22

23

24

 /**

25

  * Card List

26

  */

27

28

29

 /**

30

  * Card Dark

31

  */

Lưu ý với những phần này, bạn có thể hình dung code nên được xây dựng như thế nào. Bạn nên làm cho các định nghĩa cơ bản của card trở nên linh hoạt và đủ độc lập để bạn có thể dễ dàng triển khai card trong grid, list và phiên bản màu tối.

Sau đó, khi bạn viết code, bạn có thể nhận những nhận xét cụ thể:

1

/**

2

  * Card Base

3

  *

4

  * Defines the appearance and behaviour of the default card with its main parts:

5

  * - Card Image

6

  * - Card Content

7

  * - Card Footer

8

 */

9

10

 .card {...}

11

 .card__image {...}

12

 .card__logo {...}

13

 .card__content {...}

14

 .card__footer {...}

15

Tôi coi đây là cấp độ cơ bản của tài liệu bạn nên đưa vào bởi vì nó đóng vai trò là một hướng dẫn để bố trí code và nhanh chóng thông báo cách mọi thứ được tổ chức như thế nào để giúp người tiếp làm việc với nó.

Mức độ tiếp theo là bổ sung bình luận ​​cụ thể cho một quy tắc và có thể được sử dụng để giải thích nguyên tắc này là gì bởi vì nó không thể nhanh chóng được hiểu rõ ràng. Ví dụ:

1

/**

2

  * Card Base

3

  *

4

  * Defines the appearance and behaviour of the default card with its multiple parts:

5

  * - Card Image

6

  * - Card Logo

7

  * - Card Content

8

  * - Card Footer

9

 */

10

11

 .card {

12

   @media (max-width: {{ screen-xs }} ) {

13

     border: none;   /* because the card takes 100% of the screen on mobile */

14

   }

15

 }

16

 .card__image {...}

17

 .card__logo {...}

18

 .card__content {

19

   flex: 1 1 auto;   /* "auto" needs to be explicit to avoid the div collapsing on IE.*/

20

 }

21

Vẻ đẹp của cách tiếp cận này là có tài liệu hướng dẫn để hỗ trợ và thông báo việc thực hiện, trái ngược với điều gì đó sẽ được bổ sung vào sau đó.

Dưới đây là một vài ví dụ về framework Bootstrap hiển thị khi nào thì ý kiến ​​hữu dụng và khi nào cần phải sâu vào chi tiết hơn.

Thí dụ

1

// Need .dropdown-toggle since :last-child doesn't apply, 

2

 // given that a .dropdown-menu is used immediately after it

3

4

 .btn-group > .btn:last-child:not(:first-child),

5

 .btn-group > .dropdown-toggle:not(:first-child) {

6

  .border-left-radius(0);

7

 }

Bình luận này làm rõ lý do tại sao những phong cách này tồn tại và những gì họ đang làm. Nó cũng ngắn gọn và đến mức, truyền đạt ý tưởng bằng một ngôn ngữ giản dị.

Ví dụ #2

1

// Checkbox and radio options

2

 //

3

 // In order to support the browser's form validation feedback, powered by the

4

 // `required` attribute, we have to "hide" the inputs via `clip`. We cannot use

5

 // `display: none;` or `visibility: hidden;` as that also hides the popover.

6

 // Simply visually hiding the inputs via `opacity` would leave them clickable in

7

 // certain cases which is prevented by using `clip` and `pointer-events`.

8

 // This way, we ensure a DOM element is visible to position the popover from.

9

 //

10

 // See https://github.com/twbs/bootstrap/pull/12794 and

11

 // https://github.com/twbs/bootstrap/pull/14559 for more information.

12

13

 [data-toggle="buttons"] {

14

  > .btn,

15

  > .btn-group > .btn {

16

    input[type="radio"],

17

    input[type="checkbox"] {

18

      position: absolute;

19

      clip: rect(0,0,0,0);

20

      pointer-events: none;

21

    }

22

  }

23

 }

Đây là một ví dụ điển hình về tài liệu sâu vào chi tiết, giải thích logic đằng sau quyết định triển khai và cung cấp liên kết đến nguồn thông tin bổ sung.

Thực hiện bước tiếp theo

Với những thực tiễn tốt nhất này, bước tiếp theo là kết hợp một hướng dẫn về một style guide đang hiện hữu thành một phần của tài liệu của bạn. Một style guide hiện có là một tài liệu sống thể hiện các bình luận mà bạn đã đưa vào trong code được cấu trúc giống như một trang web, do đó bạn có thể điều hướng tài liệu tách biệt với mã nguồn.

Điều làm cho một style guide mạnh mẽ là tài liệu thực tế tồn tại cùng với code và có thể dễ dàng cập nhật khi mã của bạn thay đổi, cho phép nó được đồng bộ và có liên quan. Thêm một lợi thế nữa là tài liệu này có sẵn cho những người khác trong nhóm của bạn (có thể không tương tác trực tiếp với code) như nhà thiết kế, nhà quản lý sản phẩm hoặc kỹ sư QA. Những thành viên trong nhóm này cũng thấy hữu ích khi biết UI đang hình thành như thế nào.

Trong hướng dẫn style guide hiện hành, bạn có thể kèm các minh hoạ có tính tương tác về code và bạn có thể tổ chức tài liệu một cách độc lập với cấu trúc code.

Tổng kết

Việc làm tài liệu cho CSS bắt đầu với các quy tắc rõ ràng và một cơ sở code có cấu trúc tốt. Khi hoàn thành sẽ trở thành một phần của quy trình làm việc của bạn, nó cũng có thể đóng vai trò như một hướng dẫn về cấu trúc code của bạn và giúp code đó được tổ chức tốt khi phát triển. Điều này có thêm lợi ích của việc làm rõ mọi thứ đang ở đâu và ở đâu nên thêm code mới, dễ dàng cho việc huấn luyện các thành viên mới khi việc phát triển theo dõi nhanh.

Bài viết hữu ích

• styleguidedrivendevelopment.com

• 
  Documentation
  Documenting Your Projects With Daux.io
  Daniel Pataki
• 
  CSS
  Understanding CSS Stats: How to Make the Most of the Numbers
  Jonathan Cutrell

Nhắc lại: 8 thực tiễn tốt nhất

1. Thiết lập các quy tắc cơ bản
2. Tìm điểm trọng tâm của việc xây dựng tài liệu
3. Lập index (chỉ mục) nội dung stylesheet của bạn
4. Phân chia stylesheet của bạn thành những thành phần
5. Ghi nhớ xây dựng tài liệu CSS với một style guide
6. Tránh các stylesheet dài dòng
7. Thiết lập các tiêu chuẩn về code của bạn
8. Giải thích cấu trúc cơ sở mã của bạn